سياسة MessageLogin

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

الأدوات المستخدمة

من أفضل الطرق لتتبُّع المشاكل في بيئة وقت تشغيل واجهة برمجة التطبيقات هو تسجيل الرسائل. يمكنك إرفاق سياسة MessageLogging وضبطها على واجهة برمجة التطبيقات لتسجيل الرسائل المخصّصة في قرص محلي (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>

مرجع العنصر

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

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

<FileName>mylog.log</FileName>

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

المخططات

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

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

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

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

بما أنّه يتم تنفيذها بغض النظر عمّا إذا كان الخادم الوكيل قد نجح أو تعذّر، يمكنك وضع سياسات MessageLogging في 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 الرسائل المسجّلة في الذاكرة إلى مخزن مؤقت. يقرأ مسجّل الرسائل الرسائل من المخزن المؤقت ثم يكتبها في الوجهة التي تحدّدها. لكل وجهة مخزن مؤقت خاص بها.

قد يواجه المستخدمون تأخيرًا في تلقّي رسائل السجلّ المُرسَلة إلى نقطة نهاية جديدة لنظام syslog. ويحدث ذلك بسبب سلوك "التشغيل على البارد" المقصود في السياسة. عند ضبط وجهة تسجيل جديدة، بالإضافة إلى وجهات التسجيل الحالية، قد يبدأ "معالج الرسائل" (MP) بتخزين 1,000 رسالة سجل في الذاكرة مؤقتًا قبل إرسالها. وقد يؤدي ذلك إلى حدوث تأخير أولي في البيئات التي تشهد عددًا قليلاً من الزيارات. لا يمكن ملاحظة هذا التأخير الأوّلي في أحمال العمل النموذجية في مرحلة الإنتاج، لأنّه من المفترض أن تتراكم الرسائل بسرعة. بعد استيفاء الحدّ، سيتم تسليم رسائل السجلّ على النحو المتوقّع. يمكن أن تؤدي إعادة التشغيل السلسة لـ "معالج الرسائل" أيضًا إلى بدء تسليم الرسائل الموضوعة في قائمة الانتظار أثناء إزالتها من القائمة.

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

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 إذا كان المسار السابق هو Error Flow. إذا أردت تسجيل معلومات الردود من 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" للتحكّم في هذا التنسيق. على سبيل المثال، تغيير تنسيق الرسالة إلى:

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

..replacing the dashes with slashes, and shortening to a 2-digit year, records a timestamp in the form:

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" (Edge Message Processor):
   > /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 property على 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 إرسال رسائل syslog إلى خدمات إدارة السجلّات التابعة لجهات خارجية، مثل Splunk وSumo Logic وLoggly. إذا أردت إرسال syslog إلى إحدى هذه الخدمات، راجِع مستندات الخدمة لمعرفة كيفية ضبط المضيف والمنفذ والبروتوكول الخاصين بالخدمة، ثم اضبط عنصر Syslog في هذه السياسة وفقًا لذلك.

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

• Splunk (اختَر إصدار المنتج)
  يمكنك أيضًا الاطّلاع على منشور "منتدى Apigee" هذا: تسجيل الرسائل في Splunk
• Sumo Logic
  • راجِع أيضًا مشاركة "منتدى Apigee" التالية: إعداد تسجيل الدخول باستخدام Sumo Logic، أي مضيف يجب استخدامه؟
  • للاطّلاع على مثال كامل يستخدم Sumo Logic كخدمة تسجيل، راجِع مشاركة "منتدى Apigee" التالية. يستخدم الحلّ سياسة JavaScript واحدة لتقديم طلبات HTTP POST إلى أداة تجميع مصادر HTTP في Sumo Logic: تسجيل البيانات في Sumo Logic باستخدام JavaScript وHTTP
• Loggly
  عند استخدام Loggly، يجب توفير <FormatMessage>true</FormatMessage> في السياسة كعنصر فرعي من العنصر <Syslog>.
  يمكنك أيضًا الاطّلاع على منشور "منتدى Apigee" هذا للحصول على مزيد من المعلومات حول تسجيل الرسائل في Loggly: تسجيل الرسائل في Loggly

مرجع الخطأ

يصف هذا القسم رموز الخطأ ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تم ضبطها من خلال 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: مرجع المتغيّرات