سياسة MessageLogin

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. المعلومات

الموضوع

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

عيّنات

<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>

مرجع العنصر

استخدم العناصر التالية لضبط نوع سياسة MessageLogging.

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

المخططات

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

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

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

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

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

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

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

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

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

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

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

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

Log message size exceeded. Increase the max message size setting

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

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

بالنسبة إلى برنامج Edge for Private Cloud 4.16.01 والإصدارات الأحدث، اضبط السمة conf_message-logging_max.log.message.size.in.kb في ملف /opt/apigee/customer/application/message-processor.properties وأعِد تشغيل "معالج الرسائل".

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

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

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

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

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

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

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

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 إعادة تشغيل

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

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

تتوفر سجلات الرسائل الخاصة على السحابة الإلكترونية تلقائيًا في الدليل التالي على عُقد معالج الرسائل:

/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 على "صحيح" في ملف 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 إعادة تشغيل

Edge لـ 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>

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

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

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

• 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: مرجع المتغيّرات