MessageLogging 政策

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

您可以透過「MessageLogging��政策，將自訂訊息記錄至 Cloud Logging 或 syslog。您可以使用記錄中的資訊執行各種工作，例如追蹤 API 執行階段環境中的問題。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

您可以透過兩種方式使用「MessageLogging」政策：

• <CloudLogging> 元素會將訊息記錄至 Cloud Logging。如要使用這個方法，您必須為 Google Cloud 專案啟用 Cloud Logging API。如要進一步瞭解如何為 Google Cloud 專案啟用 API，請參閱「啟用及停用服務」。
• <Syslog> 元素會將訊息記錄到 syslog，這是用於將系統記錄檔或事件訊息傳送至特定伺服器的標準通訊協定。如要使用這種方法，您必須有可用的 syslog 伺服器。如果沒有，您可以使用公開記錄管理服務，例如 Splunk、Sumo Logic 和 Loggly。請參閱設定第三方記錄管理服務。

注意：您不能在同一個政策中同時使用 <CloudLogging> 元素和 <Syslog> 元素。

<MessageLogging> 元素

定義 <MessageLogging> 政策。

<MessageLogging> 元素使用以下語法：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1">
    <DisplayName>Message Logging-1</DisplayName>
    <Syslog>
<!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. -->
        <Message>Some message for syslog</Message>
        <Host>localhost</Host>
        <Port>514</Port>
    </Syslog>
    <CloudLogging>
<!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. -->
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>api</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

這個元素包含下列所有政策都適用的屬性：

下表概略說明 <MessageLogging> 的子元素：

範例

<MessageLogging name="LogToCloudLogging">
    <CloudLogging>
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>api</ResourceType>
    </CloudLogging>
</MessageLogging>

{"{message.queryparam.key}": "{message.queryparam.value}"}

<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>yyMMdd-HH:mm:ss.SSS</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>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

子元素參照

以下各節說明 <MessageLogging> 的子元素。

<CloudLogging>

使用 <CloudLogging> 元素將訊息記錄至 Cloud Logging。

<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>

Cloud Logging 的驗證

如要使用 <CloudLogging> 元素，您必須部署 API 代理程式，以便使用 Google 驗證機制。Apigee 會使用與您在 Cloud Logging 對外要求中指定的服務帳戶身分相對應的憑證。詳情請參閱「使用 Google 驗證」。

您在部署時附加至 API Proxy 的服務帳戶，必須具備具有 logging.logEntries.create 權限的角色。除非您需要更精細的控管，否則建議您為服務帳戶使用更廣泛的預先定義角色 roles/logging.logWriter。如要進一步瞭解 <CloudLogging> 的 Identity and Access Management (IAM) 角色，請參閱存取權控管指南。

Apigee Hybrid 中的 Proxy 部署作業

如果您使用 Apigee hybrid，為 Apigee hybrid 建立的 執行階段服務帳戶必須模擬 Proxy 服務帳戶，才能代表該帳戶發出經過驗證的呼叫。因此，Apigee 混合式執行階段服務帳戶必須具備 Proxy Service Account 的 iam.serviceAccountTokenCreator 角色。

<Syslog>

使用 <Syslog> 元素設定要記錄至 syslog 的訊息。使用 <Syslog> 時，API Proxy 會將 Apigee 的記錄訊息轉送至遠端 syslog 伺服器。如要使用這種方法，您必須有可用的 syslog 伺服器。如果沒有，您可以使用 Splunk、Sumo Logic 和 Loggly 等公開記錄管理服務。請參閱「設定第三方記錄管理服務」。

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

<logLevel>

<logLevel> 元素的有效值為：INFO (預設)、ALERT、WARN、ERROR。

設定要納入訊息記錄中的特定資訊層級。

如果您使用 FormatMessage 元素 (將其設為 true)，<logLevel> 設定會影響 Apigee 產生資訊中 (附加在訊息前端) 計算出的優先順序分數 (尖括號內的數字)。

使用須知

將 MessageLogging 政策附加至 API Proxy 流程時，建議將其放在 ProxyEndpoint 回應中，也就是名為 PostClientFlow 的特殊流程中。回應傳送至要求的用戶端後，PostClientFlow 就會執行，確保所有指標可供記錄。如要進一步瞭解如何使用 PostClientFlow，請參閱「API Proxy 設定參考資料」。

PostClientFlow 有兩種特殊之處：

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

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

下圖顯示在 DefaultFaultRule 執行後，MessageLogging 政策會在 PostClientFlow 中執行：

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

以下是包含 PostClientFlow 的 ProxyEndpoint 定義：

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

Apigee 會將訊息記錄為簡單文字，您可以設定記錄功能，納入變數，例如收到要求或回應的日期和時間、要求中的使用者身分、傳送要求的來源 IP 位址等等。

Apigee 會以非同步方式記錄訊息：回應會在記錄仍在寫入時傳回。因此，封鎖呼叫不會導致 API 延遲。在某些情況下，如果沒有傳回錯誤，記錄可能就不會寫入，但這種情況很少發生。

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

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

• 使用 <CloudLogging>：

  steps.messagelogging.TooManyPendingLoggingRequest

• 使用 <Syslog>：

  Log message size exceeded. Increase the max message size setting

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

訊息範本中變數的預設值

您可以為訊息範本中的每個變數分別指定預設值。舉例來說，如果無法解析變數 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 社群的這篇文章： 將訊息記錄到 Splunk
• Sumo Logic
  • 另請參閱 Apigee 社群的這篇貼文：使用 Sumo Logic 設定記錄
  • 如需使用 Sumo Logic 做為記錄服務的完整範例，請參閱下列 Apigee 社群文章。這個解決方案使用單一 JavaScript 政策，向 Sumo Logic HTTP 來源收集器提出 HTTP POST 要求：使用 JavaScript 和 HTTP 將記錄記錄到 Sumo Logic
• Loggly
  使用 Loggly 時，政策中必須有 <FormatMessage>true</FormatMessage>，做為 <Syslog> 元素的子項。
  如要進一步瞭解如何將訊息記錄到 Loggly，請參閱這篇 Apigee 社群文章： 將訊息記錄到 Loggly

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

部署錯誤

部署含有這項政策的 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

相關主題

• Apigee 公開的變數：流程變數參考資料