MessageLogging 政策

您目前查看的是 Apigee Edge 說明文件。
參閱 Apigee X說明文件。 資訊

內容

在 API 執行階段環境中追蹤問題的最佳方式之一，就是記錄訊息。您可以在 API 中附加並設定 MessageLogging 政策，將自訂訊息記錄到本機磁碟 (僅限私有雲的 Edge) 或 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 流程時，請考慮將 MessageLogging 政策放入 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

如果您在 Private Cloud 4.15.07 以下版本中遇到此問題，請找出 message-logging.properties 檔案，並使用這個解決方案：

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

如果是 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 物件。不論是否有錯誤，您都可以使用這個物件，從回應取得標頭和其他資訊。詳情請參閱「訊息變數」一節和範例。

控管 Private Cloud 中 Edge 中的記錄訊息時間戳記

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

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. 重新啟動邊緣訊息處理器：
   > /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 社群貼文：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-that-host-shou.html
  • 如需使用 Sumo Logic 做為記錄服務的完整範例，請參閱下列 Apigee 社群文章。這項解決方案使用單一 JavaScript 政策，向 Sumo Logic HTTP 來源收集器提出 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

錯誤參考資料

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

執行政策時，可能會發生這些錯誤。

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

錯誤回應範例

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