سياسة MessageLogin

أنت تطّلع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

ما هي الإعلانات الترويجية؟

من أفضل الطرق لتتبُّع المشاكل في بيئة وقت تشغيل واجهة برمجة التطبيقات هي تسجيل الرسائل. يمكنك إرفاق سياسة تسجيل الرسائل وضبطها على واجهة برمجة التطبيقات لتسجيل الرسائل المخصّصة على ملف شخصي على القرص (Edge for Private Cloud فقط) أو في syslog.

نماذج

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <DateFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

<MessageLogging name="LogToSyslog">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

مرجع العنصر

استخدِم العناصر التالية لضبط نوع سياسة "تسجيل الرسائل".

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

المخططات

ملاحظات الاستخدام

عند إرفاق سياسة تسجيل الرسائل بمسار وكيل واجهة برمجة التطبيقات، ننصحك بوضعها في ملف تعريف الردّ ProxyEndpoint، في مسار خاص يُسمى PostClientFlow. يتم تنفيذ PostClientFlow بعد إرسال الردّ إلى العميل الذي طلبه، ما يضمن توفّر جميع المقاييس لتسجيلها. لمعرفة التفاصيل حول استخدام PostClientFlow، يُرجى الاطّلاع على مرجع إعداد الخادم الوكيل لواجهة برمجة التطبيقات.

يتميز PostClientFlow بطريقتَين:

1. ولا يتم تنفيذه إلا كجزء من عملية الردّ.
2. وهي العملية الوحيدة التي يتم تنفيذها بعد دخول الخادم الوكيل إلى حالة الخطأ.

ولأنّه يتم تنفيذه بغض النظر عمّا إذا كان الخادم الوكيل ناجحًا أو تعذّر عليه إكمال المهمة، يمكنك وضع سياسات تسجيل الرسائل في PostClientFlow والتأكّد من تنفيذها دائمًا.

تعرض صورة التتبّع التالية سياسة MessageLogging التي يتم تنفيذها كجزء من PostClientFlow، بعد تنفيذ DefaultFaultRule:

في هذا المثال، أدّت سياسة التحقّق من مفتاح واجهة برمجة التطبيقات إلى حدوث الخطأ بسبب مفتاح غير صالح.

في ما يلي تعريف ProxyEndpoint الذي يتضمّن PostClientFlow:

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

يسجِّل Edge الرسائل كنص بسيط، ويمكنك ضبط التسجيل لتضمين متغيّرات، مثل التاريخ والوقت اللذَين تم استلام الطلب أو الاستجابة فيهما، وهوية المستخدم في الطلب، عنوان IP المصدر الذي تم إرسال الطلب منه، وما إلى ذلك. يسجِّل Edge الرسائل بشكل غير متزامن، ما يعني أنّه لا يتم إدخال أي وقت استجابة قد ينتج عن حظر العناصر التي تشير إلى نص في "واجهة برمجة التطبيقات".

تُسجِّل سياسة "تسجيل الرسائل" الرسائل المسجَّلة في الذاكرة في ذاكرة تخزين مؤقت. يقرأ مُسجِّل الرسائل الرسائل من المخزن المؤقت ثم يكتبها في الوجهة التي تحدّدها. ولكل وجهة مخزن مؤقت خاص بها.

إذا زاد معدّل الكتابة إلى المخزن المؤقت عن معدّل القراءة، سيحدث فائض في المخزن المؤقت، وبالتالي لن تتم عملية تسجيل البيانات. في حال حدوث ذلك، قد تظهر لك رسالة تتضمّن ما يلي في ملف السجلّ:

Log message size exceeded. Increase the max message size setting

إذا واجهت هذه المشكلة في الإصدار 4.15.07 من Edge for Private Cloud والإصدارات الأقدم، ابحث عن ملف message-logging.properties واستخدِم هذا الحل:

عليك زيادة سمة max.log.message.size.in.kb (القيمة التلقائية = 128 كيلوبايت) فيملف message-logging.properties.

بالنسبة إلى Edge for Private Cloud 4.16.01 والإصدارات الأحدث، اضبط السمة conf/message-logging.properties+max. log.message.size.in.kb في ملف /opt/apigee/customer/application/message-processor.properties وأعِد تشغيل Message Processor. يُرجى العلم أنّ هذه السمة تكون مشطوبة تلقائيًا في البداية.

ملاحظة: لا تتوفّر متغيّرات رسالة الردّ في Edge من مسار الخطأ. ولا تكون هذه المتغيّرات متوفرة أيضًا في PostClientFlow إذا كان المسار السابق هو مسار الخطأ. إذا كنت تريد تسجيل معلومات الردّ من PostClientFlow، استخدِم العنصر message. يمكنك استخدام هذا العنصر للوصول إلى العناوين والمعلومات الأخرى من الاستجابة سواء حدث خطأ أم لا. اطّلِع على متغيّرات الرسالة للحصول على مزيد من المعلومات والاطّلاع على مثال.

التحكّم في الطابع الزمني لرسائل السجلّ في Edge for Private Cloud

يكون الطابع الزمني في جميع رسائل السجلّات تلقائيًا بالتنسيق التالي:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

يمكن إلغاء هذه القيمة التلقائية على مستوى النظام لوجهَات syslog باستخدام العنصر DateFormat. يتم وصف سلوك هذا النموذج في مستندات فئة SimpleDateFormat في Java. وفقًا لهذا التعريف، سيتم استبدال yyyy برقم السنة المكوّن من 4 أرقام، وسيتم استبدال MM برقم الشهر المكوّن من رقمين، وهكذا. قد يؤدي التنسيق أعلاه إلى سلسلة بهذا الشكل:

2022-09-28T22:38:11.721+0000

يمكنك استخدام السمة conf_system_apigee.syslogger.dateFormat في Edge Message Processor للتحكّم في هذا التنسيق. على سبيل المثال، تغيير تنسيق الرسالة إلى:

yy/MM/dd'T'HH:mm:ss.SSSZ

..عند استبدال الشُرطات بشرطات مائلة وتقصير السنة إلى رقمين، يتم تسجيل طابع زمني بالشكل التالي:

22/09/28T22:38:11.721+0000

لتغيير التنسيق:

1. افتح ملف message-processor.properties في محرِّر. إذا لم يكن الملف متوفّرًا، أنشِئه:
   > vi /opt/apigee/customer/application/message-processor.properties
2. اضبط السمات على النحو المطلوب:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. احفظ التغييرات.
4. تأكَّد من أنّ ملف الخصائص يملكه المستخدم "apigee":
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. أعِد تشغيل "معالج الرسائل في Edge":
   > ‎/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

موقع ملف السجلّ في Edge for Private Cloud

‫Edge for Private Cloud 4.16.01 والإصدارات الأحدث

تتوفّر سجلّات رسائل Private Cloud تلقائيًا في الدليل التالي على عقد Message Processor:

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

يمكنك تغيير الموقع التلقائي للسجلّ من خلال تعديل السمات فيملف message-logging.properties في "معالجات الرسائل":

• ‫bin_setenv_data_dir: يضبط المسار الجذر لتخزين ملفات السجلّ. على سبيل المثال، bin_setenv_data_dir=/opt/apigee/var/log
• ‫conf_message-logging_log.root.dir: إذا ضبطت هذا الخيار على مسار نسبي، مثل conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.
  
  إذا ضبطت هذا الخيار على مسار مطلق، مثل conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages، سيتم تخزين سجلّات الرسائل في /opt/apigee/var/log/messages/messagelog/. يكون للمسار المطلق الأولوية على bin_setenv_data_dir.
  
  يُرجى العِلم أنّه عليك الإشارة إلى السمة باسم conf/message-logging.properties+log.root.dir لأنّه تم وضع تعليق عليه تلقائيًا. اطّلِع على ضبط رمز مميّز تم تعليقه حاليًا لمعرفة المزيد.

إذا كنت تريد تخزين ملفات السجلّ في بنية ملف مسطّح حتى يتم وضع جميع ملفات السجلّ في الدليل نفسه، اضبط conf/message-logging.properties+enable.flat.directory.structure على true في ملف message-logging.properties. يتم تخزين الرسائل في الدليل المحدّد من قِبل السمات أعلاه، وتتخذ أسماء الملفات شكل {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

لضبط هذه السمات:

1. افتح ملف message-processor.properties في محرِّر. إذا لم يكن الملف متوفّرًا، أنشِئه:
   > vi /opt/apigee/customer/application/message-processor.properties
2. اضبط السمات على النحو المطلوب:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. احفظ التغييرات.
4. تأكَّد من أنّ ملف الخصائص يملكه المستخدم "apigee":
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. أعِد تشغيل مكوّن Edge:
   > ‎/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud 4.15.07 والإصدارات الأقدم

تتوفّر سجلّات الرسائل تلقائيًا في الموقع التالي على معالجات الرسائل:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

يمكنك تغيير الموقع التلقائي للسجلّ من خلال تعديل السمات التالية فيملف message-logging.properties على معالجات الرسائل:

• ‫data.dir: لضبط مسار الجذر لتخزين ملفات السجلّ على سبيل المثال، data.dir=‎/opt/apigee4/var/log
• ‫log.root.dir: في حال ضبط هذا الخيار على مسار نسبي، مثل log.root.dir=custom/folder/، تتم إضافة المسار إلى موقع data.dir.

على سبيل المثال، سيؤدي الجمع بين السمتَين إلى ضبط دليل التسجيل على ‎/opt/apigee4/var/log/custom/folder/messagelog/ (يُرجى العلم أنّه تتم إضافة ‎ /messagelog تلقائيًا).

في حال ضبط هذا الإعداد على مسار مطلق، مثل log.root.dir=/opt/apigee4/var/log/messages، سيتم تخزين سجلات الرسائل في ‎ /opt/apigee4/var/log/messages/messagelog/. يكون للمسار المطلق في log.root.dir الأولوية على data.dir.

إذا كنت تريد تخزين ملفات السجلّ في بنية ملف مسطّح حتى يتم وضع جميع ملفات السجلّ في الدليل نفسه، اضبط السمة enable.flat.directory.structure على true في ملف message-logging.properties على معالجات الرسائل. يتم تخزين الرسائل في الدليل المحدّد من خلال السمات أعلاه، وتأخذ أسماء الملفات التنسيق {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

القيم التلقائية للمتغيّرات في نموذج الرسالة

يمكن تحديد القيم التلقائية لكل متغيّر في نموذج الرسالة بشكل منفصل. على سبيل المثال، إذا تعذّر حلّ المتغيّر request.header.id، يتم استبدال قيمته بالقيمة unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

يمكن تحديد قيمة تلقائية شائعة لجميع المتغيّرات التي لم يتم حلّها من خلال ضبط سمة defaultVariableValue على العنصر Message:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

ضبط خدمات إدارة السجلّات التابعة لجهات خارجية

تتيح لك سياسة تسجيل الرسائل إرسال رسائل syslog إلى خدمات إدارة السجلّات التابعة لجهات خارجية، مثل Splunk وSumo Logic وLoggly. إذا أردت إرسال syslog إلى إحدى هذه الخدمات، اطّلِع على مستندات هذه الخدمة لضبط مضيف الخدمة ومنفذها وبروتوكولها، ثم اضبط عنصر Syslog في هذه السياسة وفقًا لذلك.

اطّلِع على المستندات التالية لضبط إدارة السجلّات التابعة لجهة خارجية:

• Splunk (اختَر إصدار المنتج)
  يمكنك أيضًا الاطّلاع على مشاركة "منتدى Apigee" هذه: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html.
• Sumo Logic
  • يمكنك أيضًا الاطّلاع على مشاركة "منتدى Apigee" هذه: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • للحصول على مثال كامل لاستخدام Sumo Logic كخدمة تسجيل، اطّلِع على مشاركة التالية في منتدى Apigee. يستخدم الحل سياسة JavaScript واحدة لتقديم طلبات HTTP POST إلى أداة جمع مصادر HTTP في Sumo Logic: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  عند استخدام Loggly، يجب إدراج <FormatMessage>true</FormatMessage> في السياسة كعنصر فرعي للعنصر <Syslog>.
  يمكنك أيضًا الاطّلاع على مشاركة منتدى Apigee هذه للحصول على مزيد من المعلومات حول تسجيل الرسائل في Loggly: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

مرجع الخطأ

يصف هذا القسم رموز الخطأ ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تم ضبطها من خلال Edge عندما تؤدي هذه السياسة إلى ظهور خطأ. من المهم معرفة هذه المعلومات إذا كنت تضع قواعد خطأ التعامل مع الأخطاء. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على ما تحتاج إلى معرفته حول أخطاء السياسة والتعامل مع المعالجة والأخطاء.

أخطاء بيئة التشغيل

يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.

أخطاء النشر

يمكن أن تحدث هذه الأخطاء عند نشر خادم وكيل يحتوي على هذه السياسة.

متغيّرات الأخطاء

يتم ضبط هذه المتغيّرات عند حدوث خطأ في بيئة التشغيل. يمكنك الاطّلاع على مقالة ما تحتاج إلى معرفته للحصول على مزيد من المعلومات. حول أخطاء السياسة.

مثال على استجابة الخطأ

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

مثال على قاعدة الخطأ

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>

متغيّرات التدفق

تتم تعبئة المتغيّرات التالية في حال تعذّر تطبيق السياسة.

• messagelogging.failed
• messagelogging.{stepdefinition-name}.failed

مواضيع ذات صلة

• المتغيّرات التي يعرضها Edge: مرجع المتغيّرات