MessageLogging 政策

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

記錄訊息是追蹤 API 執行階段環境中問題的最佳方法之一。您可以在 API 上附加並設定 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 政策附加至 API Proxy 流程時，請考慮將其放在 ProxyEndpoint 回應中，也就是名為 PostClientFlow 的特殊流程中。回應傳送至要求的用戶端後，PostClientFlow 就會執行，確保所有指標可供記錄。如要進一步瞭解如何使用 PostClientFlow，請參閱「API Proxy 設定參考資料」。

PostClientFlow 有兩種特殊之處：

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

無論 Proxy 是否成功或失敗，這項政策都會執行，因此您可以將 MessageLogging 政策放入 PostClientFlow，確保政策一律執行。

下圖顯示 Trace 的畫面，其中顯示在 DefaultFaultRule 執行後，PostClientFlow 執行時，MessageLogging 政策的執行情形：

在這個例子中，由於金鑰無效，導致「驗證 API 金鑰」政策造成錯誤。

以下是包含 PostClientFlow 的 ProxyEndpoint 定義：

<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 檔案並使用以下解決方案：

請在 message-logging.properties 檔案中調高 max.log.message.size.in.kb 屬性 (預設值 = 128 KB)。

如果是 Edge for Private Cloud 4.16.01 以上版本，請在 /opt/apigee/customer/application/message-processor.properties 檔案中設定 conf/message-logging.properties+max. log.message.size.in.kb 屬性，然後重新啟動 Message Processor。請注意，這個屬性一開始會預設為註解。

注意：Edge 中的回應訊息變數無法透過錯誤流程使用。如果先前的流程是錯誤流程，則 PostClientFlow 也不會提供這些變數。如果您想記錄 PostClientFlow 的回應資訊，請使用 message 物件。無論是否發生錯誤，您都可以使用這個物件，從回應中取得標頭和其他資訊。如需詳細資訊和範例，請參閱「訊息變數」。

在 Edge for Private Cloud 中控制記錄訊息時間戳記

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

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

您可以使用 DateFormat 元素，針對 syslog 目的地覆寫這個系統層級的預設值。如要瞭解這個範本的行為，請參閱 Java 的 SimpleDateFormat 類別說明文件。根據這個定義，yyyy 會替換成 4 位數的年份，MM 會替換成 2 位數的月份編號，以此類推。上述格式可能會產生以下格式的字串：

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

您可以使用 Edge Message Processor 上的 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 檔案。如果檔案不存在，請建立檔案：
   > 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 4.16.01 以上版本

根據預設，私有雲訊息記錄檔會位於 Message Processor 節點的以下目錄：

/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 的形式參照屬性，因為預設情況下會將其註解掉。詳情請參閱「設定目前已註解的符記」。

如果您想將記錄檔儲存在平面檔案結構中，以便將所有記錄檔放入相同的目錄，請在 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 Processor 的 message-logging.properties 檔案中將 enable.flat.directory.structure property 設為 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 社群的這篇文章：https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • 另請參閱 Apigee 社群的這篇文章： https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • 如需使用 Sumo Logic 做為記錄服務的完整範例，請參閱下列 Apigee 社群文章。這個解決方案使用單一 JavaScript 政策，向 Sumo Logic HTTP Source Collector 發出 HTTP POST 要求：https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  使用 Loggly 時，政策中必須包含 <FormatMessage>true</FormatMessage>，做為 <Syslog> 元素的子項。
  如要進一步瞭解如何將訊息記錄到 Loggly，請參閱這篇 Apigee 社群文章： 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 公開的變數：變數參考資料