خط مشی 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 استفاده کنید.

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

طرحواره ها

نکات استفاده

هنگام پیوست کردن یک خط مشی MessageLogging به یک جریان پروکسی API، در نظر داشته باشید که آن را در پاسخ ProxyEndpoint، در یک جریان ویژه به نام PostClientFlow قرار دهید. PostClientFlow پس از ارسال پاسخ به مشتری درخواست کننده اجرا می شود، که تضمین می کند که تمام معیارها برای ورود به سیستم در دسترس هستند. برای جزئیات در مورد استفاده از PostClientFlow، به مرجع پیکربندی پروکسی API مراجعه کنید.

PostClientFlow از دو جهت خاص است:

1. فقط به عنوان بخشی از جریان پاسخ اجرا می شود.
2. این تنها جریانی است که پس از ورود پراکسی به حالت خطا اجرا می شود.

از آنجایی که بدون توجه به موفقیت یا عدم موفقیت پروکسی اجرا می شود، می توانید سیاست های MessageLogging را در PostClientFlow قرار دهید و تضمین کنید که همیشه اجرا می شوند.

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

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

در زیر، تعریف ProxyEndpoint نشان داده شده است که شامل PostClientFlow است:

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

Edge پیام‌ها را به صورت متن ساده ثبت می‌کند و شما می‌توانید گزارش‌گیری را طوری پیکربندی کنید که شامل متغیرهایی مانند تاریخ و ساعت دریافت درخواست یا پاسخ، هویت کاربر در درخواست، آدرس IP منبعی که درخواست از آن ارسال شده است، و غیره باشد. در Edge پیام را به صورت ناهمزمان ثبت می کند، به این معنی که هیچ تاخیری که ممکن است در اثر مسدود کردن فراخوان ها ایجاد شود، به API شما وارد نمی شود.

خط مشی 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 ویژگی conf/message-logging.properties+max. log.message.size.in.kb در /opt/apigee/customer/application/message-processor.properties فایل و Message Processor را مجددا راه اندازی کنید. لطفاً توجه داشته باشید که این ویژگی در ابتدا به صورت پیش فرض اظهار نظر می شود.

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

کنترل مهر زمانی پیام گزارش در Edge for Private Cloud

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

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

این پیش‌فرض در سراسر سیستم را می‌توان برای مقاصد syslog با استفاده از عنصر DateFormat لغو کرد. رفتار این الگو در مستندات کلاس SimpleDateFormat جاوا توضیح داده شده است. با توجه به آن تعریف، yyyy با یک سال 4 رقمی، MM با یک ماه 2 رقمی جایگزین می شود و غیره. فرمت فوق ممکن است منجر به رشته ای از این فرم شود:

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

برای کنترل آن فرمت می توانید از ویژگی conf_system_apigee.syslogger.dateFormat در Edge Message Processor استفاده کنید. به عنوان مثال، تغییر قالب پیام به:

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

..جایگزینی خط تیره با اسلش و کوتاه کردن آن به یک سال 2 رقمی، یک مهر زمانی را به شکل زیر ثبت می کند:

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 برای Private Cloud ثبت کنید

Edge برای Private Cloud نسخه 4.16.01 و بالاتر

به‌طور پیش‌فرض، گزارش‌های پیام خصوصی 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/ ذخیره می‌شوند. /opt/apigee/var/log/messages/messagelog/ . یک مسیر مطلق بر bin_setenv_data_dir اولویت دارد.
  
  توجه داشته باشید که باید ویژگی را به صورت conf/message-logging.properties+log.root.dir ارجاع دهید زیرا به صورت پیش‌فرض نظر داده می‌شود. برای اطلاعات بیشتر به تنظیم نشانه ای که در حال حاضر نظر داده شده است مراجعه کنید.

اگر می‌خواهید فایل‌های گزارش را در یک ساختار فایل مسطح ذخیره کنید تا همه فایل‌های log در یک فهرست قرار گیرند، 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 برای 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 را در فایل 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 به شما امکان می دهد پیام های ثبت سیستم را به سرویس های مدیریت لاگ شخص ثالث مانند Splunk، Sumo Logic و Loggly ارسال کنید. اگر می‌خواهید syslog را به یکی از آن سرویس‌ها ارسال کنید، به اسناد آن سرویس برای پیکربندی میزبان، پورت و پروتکل سرویس مراجعه کنید، سپس عنصر Syslog را بر این اساس روی این خط‌مشی تنظیم کنید.

برای پیکربندی مدیریت لاگ شخص ثالث به مستندات زیر مراجعه کنید:

• Splunk (نسخه محصول را انتخاب کنید)
  همچنین این پست انجمن Apigee را ببینید: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• سومو منطق
  • همچنین این پست انجمن Apigee را ببینید: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • برای مثال کامل استفاده از Sumo Logic به عنوان سرویس ورود به سیستم، به پست انجمن Apigee زیر مراجعه کنید. این راه حل از یک خط مشی جاوا اسکریپت استفاده می کند تا درخواست های HTTP POST به جمع آوری کننده منبع سومو منطق HTTP: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• لاگ
  هنگام استفاده از Loggly، <FormatMessage>true</FormatMessage> به عنوان فرزند عنصر <Syslog> در خط مشی مورد نیاز است.
  همچنین برای اطلاعات بیشتر در مورد ثبت پیام به Loggly، این پست انجمن Apigee را ببینید: 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: مرجع متغیرها