سياسة 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. وهذا هو المسار الوحيد الذي يتم تنفيذه بعد دخول الخادم الوكيل إلى حالة الخطأ.

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

تعرض صورة التتبع التالية سياسة 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 for 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.properties+max. log.message.size.in.kb في ملف /opt/apigee/customer/application/message-processor.properties وأعِد تشغيل معالج الرسائل. يُرجى العلم أنّ هذا الموقع الإلكتروني يتم التعليق عليه في البداية بشكلٍ تلقائي.

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

التحكّم في الطابع الزمني لرسالة السجلّ في Edge for 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.سمات
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 for Private Cloud

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

توجد سجلات رسائل Private Cloud تلقائيًا في الدليل التالي على عُقد "معالج الرسائل":

/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.سمات
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 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/مجلد/، سيتم إلحاق المسار بموقع data.dir.

على سبيل المثال، يؤدي الجمع بين السمتَين إلى ضبط دليل التسجيل على /opt/apigee4/var/log/custom/مجلد/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 على "صحيح" في ملف 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
• منطق سومو
  • يمكنك الاطّلاع أيضًا على مشاركة "منتدى Apigee" هذه: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • للاطّلاع على مثال كامل حول استخدام Sumo Logic كخدمة التسجيل، يُرجى الاطّلاع على المشاركة التالية في منتدى Apigee. يستخدم هذا الحلّ سياسة JavaScript واحدة لإرسال طلبات HTTP POST إلى Sumo Logic HTTP Source Collector: 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: مرجع المتغيّرات