خط‌مشی MessageLogging

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

چه

یکی از بهترین راه‌ها برای ردیابی مشکلات در محیط زمان اجرای API، ثبت پیام‌ها است. می‌توانید خط‌مشی MessageLogging را به API خود پیوست و پیکربندی کنید تا پیام‌های سفارشی را در دیسک محلی (فقط 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 به جریان پراکسی API، آن را در پاسخ ProxyEndpoint، در جریان ویژه‌ای به نام PostClientFlow قرار دهید. ‫PostClientFlow پس‌از ارسال پاسخ به مشتری درخواست‌کننده اجرا می‌شود، که تضمین می‌کند همه سنجه‌ها برای ثبت گزارش دردسترس باشند. برای جزئیات مربوط به استفاده از PostClientFlow، به مرجع پیکربندی پراکسی API مراجعه کنید.

‫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 پیام را به‌صورت ناهم‌زمان ثبت می‌کند، یعنی هیچ تأخیری که ممکن است ناشی از مسدود کردن تماس‌های خروجی باشد به API شما معرفی نمی‌شود.

خط‌مشی MessageLogging پیام‌های گزارش‌شده در حافظه را در یک بافر می‌نویسد. گزارشگر پیام پیام‌ها را از بافر می‌خواند و سپس در مقصد پیکربندی‌شده می‌نویسد. هر مقصد بافر خودش را دارد.

کاربران ممکن است در دریافت پیام‌های گزارش ارسال‌شده به نقطه پایانی جدید syslog تأخیر داشته باشند. این امر به‌دلیل رفتار «شروع سرد» موردنظر در خط‌مشی است. وقتی مقصد گزارش‌گیری جدیدی پیکربندی می‌شود، علاوه بر مقصد(های) گزارش‌گیری موجود، «پردازنده پیام» (MP) ممکن است ابتدا ۱۰۰۰ پیام گزارش را در حافظه صف کند و سپس آن‌ها را ارسال کند. این امر می‌تواند منجر به تأخیر اولیه در محیط‌های کم‌ترافیک شود. این تأخیر اولیه برای حجم‌های کاری تولید معمولی قابل‌مشاهده نیست، زیرا پیام‌ها باید به‌سرعت جمع شوند. وقتی آستانه برآورده شود، پیام‌های گزارش مطابق انتظار تحویل داده خواهد شد. انجام بازراه‌اندازی تدریجی «پردازشگر پیام» نیز می‌تواند باعث راه‌اندازی ارسال پیام‌های در صف شود زیرا از صف خارج می‌شوند.

اگر نرخ نوشتن در بافر از نرخ خواندن بیشتر شود، بافر سرریز می‌شود و گزارش‌گیری ناموفق خواهد بود. اگر این اتفاق بیفتد، ممکن است پیامی حاوی موارد زیر را در فایل گزارش پیدا کنید:

Log message size exceeded. Increase the max message size setting

اگر در Edge for Private Cloud نسخه ۴.۱۵.۰۷ و نسخه‌های قدیمی‌تر با این مشکل مواجه شدید، فایل message-logging.properties را پیدا کنید و از این راه‌حل استفاده کنید:

دارایی max.log.message.size.in.kb را (مقدار پیش‌فرض = ۱۲۸ کیلوبایت) در فایل message-logging.properties افزایش دهید.

برای Edge for Private Cloud نسخه ۴.۱۶.۰۱ و نسخه‌های جدیدتر، دارایی 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

این پیش‌فرض سراسری سیستم را می‌توان برای مقصد syslog بااستفاده از عنصر DateFormat ملغی کرد. عملکرد این الگو در مستندات کلاس SimpleDateFormat در Java توضیح داده شده است. طبق آن تعریف، yyyy با سال ۴ رقمی، 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 restart

مکان فایل گزارش در Edge for Private Cloud

‫Edge for 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 را در فایل message-logging.properties روی 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 نسخه ۴.۱۵.۰۷ و نسخه‌های قدیمی‌تر

به‌طور پیش‌فرض، گزارش‌های پیام در مکان زیر در پردازنده‌های پیام قرار دارند:

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

با تنظیم کردن مشخصه 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» زیر را ببینید. این راه‌حل از یک خط‌مشی جاوا اسکریپت واحد برای ایجاد درخواست‌های HTTP POST به «جمع‌آورنده منبع HTTP» در Sumo Logic استفاده می‌کند: گزارش‌گیری در Sumo Logic بااستفاده از جاوا اسکریپت و HTTP
• Loggly
  هنگام استفاده از Loggly، <FormatMessage>true</FormatMessage> باید در خط‌مشی به‌عنوان فرزند عنصر <Syslog> وجود داشته باشد.
  همچنین برای اطلاعات بیشتر درباره ثبت پیام در Loggly، این پست «انجمن Apigee» را ببینید: ثبت پیام در 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: مرجع متغیرها