MessageLogging 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

優勢

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

範例

<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 回應的 Proxy 端點回應中，也就是名為 PostClientFlow 的特殊流程中。將回應傳送至要求端用戶端後，PostClientFlow 就會執行，確保所有指標都能記錄下來。如要進一步瞭解如何使用 PostClientFlow，請參閱 API Proxy 設定參考資料。

PostClientFlow 有以下兩種特殊之處：

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

因為無論 Proxy 是成功或失敗，系統都會執行此作業，因此您可以將 MessageLogging 政策放入 PostClientFlow 中，並確保其一律會執行。

下列追蹤圖片顯示了在 PostClientFlow 執行時一併執行的 MessageLogging 政策，該政策在執行 DefaultFaultRule 後執行：

在這個範例中，「Verify API 金鑰」政策因金鑰無效而造成錯誤。

以下顯示包含 PostClientFlow 的 ProxyEndpoint 定義：

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

邊緣記錄訊息的形式為純文字，您可以設定記錄來納入變數，例如收到要求或回應的日期和時間、要求中的使用者身分，以及傳送要求的來源 IP 位址等。邊緣記錄訊息會以非同步的方式顯示，也就是說，您的 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_max.log.message.size.in.kb 屬性，並重新啟動訊息處理器。

注意：「錯誤流程」無法使用 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

您可以使用邊緣訊息處理器的 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:apigee /opt/apigee/customer/application/message-processor.properties
5. 重新啟動邊緣訊息處理器：
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor restart

私有雲的 Edge 中的記錄檔位置

適用於 Private Cloud 4.16.01 以上版本的 Edge

根據預設，Private 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/ 中。絕對路徑的優先順序高於 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:apigee /opt/apigee/customer/application/message-processor.properties
5. 重新啟動 Edge 元件：
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor restart

適用於 Private Cloud 4.15.07 以下版本的 Edge

根據預設，訊息記錄位於訊息處理器的下列位置：

/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 傳送至其中一項服務，請參閱該服務的說明文件，設定服務的主機、通訊埠和通訊協定，然後據此設定這項政策的 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> 元素的子項。
  另外，也歡迎參閱以下 Apigee 社群文章，進一步瞭解 Loggly 的訊息記錄：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 公開的變數：變數參考資料