خط مشی MessageLogging

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

چه

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

تصویر Trace زیر، اجرای یک سیاست MessageLogging را به عنوان بخشی از PostClientFlow، پس از اجرای DefaultFaultRule نشان می‌دهد:

در این مثال، سیاست تأیید کلید API به دلیل یک کلید نامعتبر باعث ایجاد خطا شده است.

در زیر تعریف 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 برای Private Cloud 4.15.07 و نسخه‌های قبل از آن با این مشکل مواجه شدید، فایل message-logging.properties را پیدا کرده و از این راه حل استفاده کنید:

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

برای Edge برای Private Cloud نسخه ۴.۱۶.۰۱ و بالاتر، ویژگی conf/message-logging.properties+max. log.message.size.in.kb را در فایل /opt/apigee/customer/application/message-processor.properties تنظیم کرده و پردازنده پیام را مجدداً راه‌اندازی کنید. لطفاً توجه داشته باشید که این ویژگی در ابتدا به طور پیش‌فرض به صورت کامنت نمایش داده می‌شود.

توجه: متغیرهای پیام پاسخ در Edge از Error Flow در دسترس نیستند. این متغیرها در PostClientFlow نیز در صورتی که جریان قبلی Error Flow بوده باشد، در دسترس نیستند. اگر می‌خواهید اطلاعات پاسخ را از PostClientFlow ثبت کنید، از شیء message استفاده کنید. می‌توانید از این شیء برای دریافت هدرها و سایر اطلاعات از پاسخ، چه خطایی وجود داشته باشد و چه نباشد، استفاده کنید. برای اطلاعات بیشتر و مثال، به متغیرهای Message مراجعه کنید.

کنترل مهر زمانی پیام‌های لاگ در Edge برای فضای ابری خصوصی

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

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

این پیش‌فرض سراسری سیستم می‌تواند برای مقاصد syslog با استفاده از عنصر DateFormat لغو شود. رفتار این الگو در مستندات کلاس SimpleDateFormat جاوا شرح داده شده است. طبق این تعریف، 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. مطمئن شوید که فایل properties متعلق به کاربر '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 برای Private Cloud

Edge برای فضای ابری خصوصی ۴.۱۶.۰۱ و بالاتر

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

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

شما می‌توانید با تغییر ویژگی‌های فایل message-logging.properties در Message Processors، محل پیش‌فرض ثبت وقایع را تغییر دهید:

• 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. مطمئن شوید که فایل properties متعلق به کاربر '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 برای فضای ابری خصوصی ۴.۱۵.۰۷ و قبل از آن

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

/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 را در فایل message-logging.properties در Message Processors روی 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 ثبت کنید
• منطق سومو
  • همچنین به این پست انجمن Apigee مراجعه کنید: تنظیم گزارش‌گیری با Sumo Logic، از کدام میزبان باید استفاده کنم؟
  • برای یک مثال کامل با استفاده از Sumo Logic به عنوان سرویس ثبت وقایع، به پست زیر از انجمن Apigee مراجعه کنید. این راهکار از یک سیاست جاوا اسکریپت واحد برای ارسال درخواست‌های HTTP POST به Sumo Logic استفاده می‌کند. HTTP Source Collector: ثبت وقایع در Sumo Logic با استفاده از جاوا اسکریپت و HTTP
• لاگلی
  هنگام استفاده از 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 نمایش داده می‌شوند: مرجع متغیرها