MessageLogging 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

如要追蹤 API 執行階段環境中的問題，最有效的方法之一就是記錄訊息。 您可以在 API 上附加及設定 MessageLogging 政策，將自訂訊息記錄到本機磁碟 (僅限 Edge for Private Cloud) 或系統記錄檔。

範例

<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 中，保證政策一律會執行。

下圖的追蹤記錄顯示 MessageLogging 政策在 DefaultFaultRule 執行後，於 PostClientFlow 中執行：

在本例中，由於金鑰無效，Verify API Key 政策導致錯誤。

以下是包含 PostClientFlow 的 ProxyEndpoint 定義：

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

Edge 會將訊息記錄為簡單文字，您可以設定記錄檔，加入要求或回應的接收日期和時間、要求中的使用者身分、傳送要求的來源 IP 位址等變數。Edge 會非同步記錄訊息，因此不會因封鎖呼叫而導致 API 延遲。

MessageLogging 政策會將記憶體中記錄的訊息寫入緩衝區。訊息記錄器會從緩衝區讀取訊息，然後寫入您設定的目的地。每個目的地都有自己的緩衝區。

使用者可能會延遲收到傳送至新系統記錄端點的記錄訊息。這是因為政策中預期的「冷啟動」行為。設定新的記錄目的地時，除了現有的記錄目的地，訊息處理器 (MP) 也可能會先在記憶體中將 1000 則記錄訊息排入佇列，然後再傳送這些訊息。這可能會導致低流量環境中的初始延遲。對於一般生產環境工作負載，訊息應該會快速累積，因此這項初始延遲無法觀察到。達到門檻後，記錄訊息就會如預期傳送。對訊息處理器執行正常重新啟動，也可以觸發佇列訊息的傳送作業，因為這些訊息會從佇列中排空。

如果寫入緩衝區的速率超過讀取速率，緩衝區就會溢位，導致記錄作業失敗。如果發生這種情況，您可能會在記錄檔中看到包含下列內容的訊息：

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 元素，針對系統記錄目的地覆寫這項全系統預設值。如要瞭解這個範本的行為，請參閱 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 Message Processor：
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud 中的記錄檔位置

Edge for Private Cloud 4.16.01 以上版本

根據預設，私有雲訊息記錄檔位於訊息處理器節點的下列目錄中：

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

您可以為所有未解析的變數指定通用預設值，方法是在 Message 元素上設定 defaultVariableValue 屬性：

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

設定第三方記錄檔管理服務

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

如要瞭解第三方記錄檔管理設定，請參閱下列說明文件：

• Splunk (選取產品版本)
  另請參閱這篇 Apigee 社群貼文：將記錄訊息寫入 Splunk
• Sumo Logic
  • 另請參閱這篇 Apigee 社群貼文： Setting up logging with Sumo Logic, which host should I use?
  • 如需以 Sumo Logic 做為記錄服務的完整範例，請參閱下列 Apigee 社群貼文。這項解決方案會使用單一 JavaScript 政策，對 Sumo Logic HTTP 來源收集器發出 HTTP POST 要求：使用 JavaScript 和 HTTP 記錄至 Sumo Logic
• Loggly
  使用 Loggly 時，政策中必須有 <FormatMessage>true</FormatMessage>，做為 <Syslog> 元素的子項。
  如要進一步瞭解如何將訊息記錄到 Loggly，請參閱這篇 Apigee 社群貼文： 將訊息記錄到 Loggly

錯誤參考資料

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