MessageLogging नीति

आपको Apigee Edge का दस्तावेज़ दिख रहा है.
Apigee X के दस्तावेज़ पर जाएं. जानकारी

क्या

एपीआई के रनटाइम एनवायरमेंट में समस्याओं का पता लगाने का सबसे अच्छा तरीका, मैसेज लॉग करना है. अपने एपीआई पर 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. यह एक ऐसा फ़्लो है जो प्रॉक्सी के गड़बड़ी वाले स्टेटस में आने के बाद ही लागू होता है.

इसे इस बात से कोई फ़र्क़ नहीं पड़ता कि प्रॉक्सी काम कर रही है या नहीं. इसलिए, PostClientFlow में MessageLogging नीतियां लागू की जा सकती हैं. इससे यह पक्का किया जा सकता है कि वे हमेशा लागू हों.

यहां दी गई ट्रेस इमेज में, MessageLogging नीति को DefaultFaultRule के बाद PostClientFlow के हिस्से के तौर पर लागू होते हुए दिखाया गया है:

इस उदाहरण में, Verify API Key नीति का उल्लंघन हुआ है. इसकी वजह, अमान्य कुंजी है.

नीचे ProxyEndpoint की परिभाषा दी गई है, जिसमें PostClientFlow शामिल है:

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

Edge, मैसेज को सामान्य टेक्स्ट के तौर पर लॉग करता है. साथ ही, लॉगिंग को कॉन्फ़िगर करके, इसमें वैरिएबल शामिल किए जा सकते हैं. जैसे, अनुरोध या जवाब मिलने की तारीख और समय, अनुरोध करने वाले व्यक्ति की पहचान, अनुरोध भेजने वाले का सोर्स आईपी पता वगैरह. Edge, मैसेज को एसिंक्रोनस तरीके से लॉग करता है. इसका मतलब है कि कॉलआउट को ब्लॉक करने की वजह से होने वाली किसी भी तरह की देरी, आपके एपीआई में नहीं होती है.

MessageLogging नीति, लॉग किए गए मैसेज को मेमोरी में मौजूद बफ़र में लिखती है. मैसेज लॉगर, बफ़र से मैसेज पढ़ता है. इसके बाद, उन्हें उस डेस्टिनेशन पर लिखता है जिसे आपने कॉन्फ़िगर किया है. हर डेस्टिनेशन का अपना बफ़र होता है.

उपयोगकर्ताओं को नए syslog एंडपॉइंट पर भेजे गए लॉग मैसेज मिलने में देरी हो सकती है. ऐसा नीति में "कोल्ड स्टार्ट" के लिए तय किए गए व्यवहार की वजह से होता है. जब मौजूदा लॉगिंग डेस्टिनेशन के अलावा, कोई नया लॉगिंग डेस्टिनेशन कॉन्फ़िगर किया जाता है, तो मैसेज प्रोसेसर (एमपी) उन्हें भेजने से पहले, मेमोरी में 1,000 लॉग मैसेज को सबसे पहले कतार में लगा सकता है. कम ट्रैफ़िक वाले एनवायरमेंट में, इसकी वजह से शुरुआत में देरी हो सकती है. आम तौर पर, प्रोडक्शन वर्कलोड के लिए यह शुरुआती देरी नहीं दिखती, क्योंकि मैसेज तेज़ी से इकट्ठा हो जाते हैं. थ्रेशोल्ड पूरा होने के बाद, लॉग मैसेज उम्मीद के मुताबिक डिलीवर किए जाएंगे. मैसेज प्रोसेसर को ग्रेसफ़ुल तरीके से रीस्टार्ट करने पर भी, मैसेज डिलीवर हो सकते हैं. ऐसा इसलिए, क्योंकि वे मैसेज की सूची से हट जाते हैं.

अगर बफ़र में डेटा लिखने की दर, डेटा पढ़ने की दर से ज़्यादा हो जाती है, तो बफ़र ओवरफ़्लो हो जाएगा और लॉगिंग नहीं हो पाएगी. ऐसा होने पर, आपको लॉग फ़ाइल में यह मैसेज दिख सकता है:

Log message size exceeded. Increase the max message size setting

अगर आपको Edge for Private Cloud 4.15.07 और इससे पहले के वर्शन में यह समस्या आती है, तो message-logging.properties फ़ाइल ढूंढें और इस समाधान का इस्तेमाल करें:

message-logging.properties फ़ाइल में max.log.message.size.in.kb प्रॉपर्टी की वैल्यू बढ़ाएं (डिफ़ॉल्ट वैल्यू = 128 केबी).

Edge for Private Cloud 4.16.01 और इसके बाद के वर्शन के लिए, /opt/apigee/customer/application/message-processor.properties फ़ाइल में conf/message-logging.properties+max. log.message.size.in.kb प्रॉपर्टी सेट करें. इसके बाद, मैसेज प्रोसेसर को फिर से चालू करें. कृपया ध्यान दें कि यह प्रॉपर्टी, डिफ़ॉल्ट रूप से शुरू में टिप्पणी के तौर पर दिखती है.

ध्यान दें: Edge में जवाब के मैसेज वाले वैरिएबल, गड़बड़ी वाले फ़्लो से उपलब्ध नहीं होते. अगर पिछला फ़्लो, गड़बड़ी वाला फ़्लो था, तो ये वैरिएबल PostClientFlow में भी उपलब्ध नहीं होते. अगर आपको PostClientFlow से जवाब की जानकारी लॉग करनी है, तो message ऑब्जेक्ट का इस्तेमाल करें. इस ऑब्जेक्ट का इस्तेमाल करके, जवाब से हेडर और अन्य जानकारी पाई जा सकती है. इससे कोई फ़र्क़ नहीं पड़ता कि कोई गड़बड़ी हुई थी या नहीं. ज़्यादा जानकारी और उदाहरण के लिए, मैसेज वैरिएबल देखें.

Edge for Private Cloud में, लॉग मैसेज के टाइमस्टैंप को कंट्रोल करना

डिफ़ॉल्ट रूप से, सभी लॉग मैसेज में टाइमस्टैंप का फ़ॉर्मैट यह होता है:

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

पूरे सिस्टम के लिए मौजूद इस डिफ़ॉल्ट वैल्यू को, syslog डेस्टिनेशन के लिए बदला जा सकता है. इसके लिए, DateFormat एलिमेंट का इस्तेमाल करें. इस टेंप्लेट के काम करने के तरीके के बारे में, Java की SimpleDateFormat क्लास के दस्तावेज़ में बताया गया है. इस परिभाषा के मुताबिक, yyyy की जगह चार अंकों वाला साल, MM की जगह दो अंकों वाला महीना, और इसी तरह अन्य फ़ॉर्मैट इस्तेमाल किए जाएंगे. ऊपर दिए गए फ़ॉर्मैट से, इस तरह की स्ट्रिंग मिल सकती है:

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

इस फ़ॉर्मैट को कंट्रोल करने के लिए, Edge Message Processor पर conf_system_apigee.syslogger.dateFormat प्रॉपर्टी का इस्तेमाल किया जा सकता है. उदाहरण के लिए, मैसेज के फ़ॉर्मैट को इसमें बदलना:

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 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 के मैसेज लॉग, मैसेज प्रोसेसर नोड पर मौजूद इस डायरेक्ट्री में सेव होते हैं:

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

Message Processors पर मौजूद 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 के तौर पर रेफ़रंस करना होगा, क्योंकि यह डिफ़ॉल्ट रूप से टिप्पणी के तौर पर मार्क की गई है. ज़्यादा जानकारी के लिए, ऐसे टोकन को सेट करना जिस पर फ़िलहाल टिप्पणी की गई है लेख पढ़ें.

अगर आपको लॉग फ़ाइलों को फ़्लैट फ़ाइल स्ट्रक्चर में सेव करना है, ताकि सभी लॉग फ़ाइलें एक ही डायरेक्ट्री में रखी जा सकें, तो message-logging.properties फ़ाइल में conf/message-logging.properties+enable.flat.directory.structure को true पर सेट करें. मैसेज, ऊपर दी गई प्रॉपर्टी के हिसाब से तय की गई डायरेक्ट्री में सेव किए जाते हैं. साथ ही, फ़ाइल के नाम {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 पर प्राथमिकता दी जाती है.

अगर आपको लॉग फ़ाइलों को फ़्लैट फ़ाइल स्ट्रक्चर में सेव करना है, ताकि सभी लॉग फ़ाइलें एक ही डायरेक्ट्री में रखी जा सकें, तो मैसेज प्रोसेसर पर मौजूद message-logging.properties फ़ाइल में, enable.flat.directory.structure प्रॉपर्टी को true पर सेट करें. ये मैसेज, ऊपर दी गई प्रॉपर्टी के हिसाब से तय की गई डायरेक्ट्री में सेव किए जाते हैं. साथ ही, फ़ाइल के नाम इस फ़ॉर्म में होते हैं: {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>

Message एलिमेंट पर defaultVariableValue एट्रिब्यूट सेट करके, सभी अनसुलझे वैरिएबल के लिए एक सामान्य डिफ़ॉल्ट वैल्यू तय की जा सकती है:

<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 Community की यह पोस्ट भी देखें: Sumo Logic के साथ लॉगिंग सेट अप करते समय, मुझे किस होस्ट का इस्तेमाल करना चाहिए?
  • लॉगिंग सेवा के तौर पर Sumo Logic का इस्तेमाल करने का पूरा उदाहरण देखने के लिए, Apigee कम्यूनिटी की यह पोस्ट देखें. इस समाधान में, Sumo Logic HTTP सोर्स कलेक्टर को एचटीटीपी पोस्ट अनुरोध भेजने के लिए, एक JavaScript नीति का इस्तेमाल किया जाता है: JavaScript और एचटीटीपी का इस्तेमाल करके Sumo Logic में लॉग करना
• Loggly
  Loggly का इस्तेमाल करते समय, नीति में <FormatMessage>true</FormatMessage> को <Syslog> एलिमेंट के चाइल्ड के तौर पर शामिल करना ज़रूरी है.
  Loggly में मैसेज लॉग करने के बारे में ज़्यादा जानकारी के लिए, Apigee कम्यूनिटी की यह पोस्ट भी देखें: Loggly में मैसेज लॉग करना

गड़बड़ी की जानकारी

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

<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 की ओर से दिखाए गए वैरिएबल: वैरिएबल का रेफ़रंस