سياسة 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.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 for Private Cloud

Edge for 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 على 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

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/column/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 منطق
  • اطّلِع أيضًا على مشاركة منتدى 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: مرجع المتغيّرات