MessageLogging 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

在 API 執行階段環境中追蹤問題的最佳方式之一，就是記錄訊息。 您可以在 API 中附加並設定 MessageLogging 政策，以便記錄自訂訊息 (僅限 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 Proxy 流程時，請考慮將其置於 ProxyEndpoint 回應，在名為 PostClientFlow 的特殊流程中。PostClientFlow 會執行 能確保所有指標都可供使用 。如要進一步瞭解如何使用 PostClientFlow，請參閱 API Proxy 設定參考資料。

PostClientFlow 具有以下特點：

1. 此類別只會在回應流程中執行。
2. 這是 Proxy 進入錯誤狀態後所執行的唯一流程。

由於 Proxy 會執行，無論 Proxy 成功還是失敗，您都可以將 PostClientFlow 中的 MessageLogging 政策，並保證這類政策一律會執行。

下列 Trace 圖片顯示，MessageLogging 政策在 PostClientFlow，在 DefaultFaultRule 執行後：

在本例中，因「驗證 API 金鑰」政策無效而導致錯誤 鍵。

以下為包含 PostClientFlow 的 ProxyEndpoint 定義：

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

Edge 會將訊息記錄為簡單的文字，您可以調整記錄設定來納入變數，例如 收到要求或回應的日期和時間、要求中的使用者身分、 傳送要求的來源 IP 位址等邊緣記錄訊息 這表示不會因為封鎖呼叫而造成延遲 至 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 KB) 調高 message-logging.properties 檔案。

如果是 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 私有雲中的時間戳記

根據預設，所有記錄訊息中的時間戳記格式如下：

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

可使用 DateFormat 元素。如要瞭解此範本的行為，請參閱 Java 的 SimpleDateFormat 類別說明文件。根據這項定義，將會取代 yyyy 帶有 4 位數的年份，MM 將替換為 2 位數的月份，以此類推。 上述格式會產生這個格式的字串：

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

您可以使用 conf_system_apigee.syslogger.dateFormat 屬性控制該格式。例如變更訊息 轉換為：

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

..將破折號取代為正斜線，並將破折號縮短為 2 位數年份，記錄在下列格式的時間戳記：

22/09/28T22:38:11.721+0000

如何變更格式：

1. 開啟 message-processor.properties 編輯。如果檔案不存在，請建立檔案：
   >V 罩杯 /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. 重新啟動邊緣訊息處理器：
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor restart 設為

Edge for Private Cloud 中的記錄檔位置

Edge for Private Cloud 4.16.01 以上版本

根據預設，Private Cloud 訊息記錄位於 Message 的下列目錄 處理器節點：

/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。訊息會儲存在 屬性，而檔案名稱的格式為 {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}。

如何設定這些屬性：

1. 開啟 message-processor.properties 編輯。如果檔案不存在，請建立檔案：
   >V 罩杯 /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。

如何以一般檔案結構儲存記錄檔，讓所有的記錄檔都放在 相同目錄，請將 enable.flat.directory.structure 屬性設為 在訊息上的 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>

您可以設定 Message 元素的 defaultVariableValue 屬性：

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

設定第三方記錄管理服務

MessageLogging 政策可讓您將系統記錄訊息傳送至第三方記錄管理 例如 Splunk、Sumo Logic 和 Loggly。如果您想將系統記錄傳送給其中一個 請參閱該服務的說明文件，瞭解如何設定服務的主機、通訊埠和通訊協定 然後據此設定這項政策的 Syslog 元素。

請參閱下列第三方記錄管理設定說明文件：

• 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 向 Sumo Logic HTTP 來源收集器提出要求：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

錯誤參考資料

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 公開的變數：變數參考資料