MessageLogging 政策

本頁適用於 ApigeeApigee 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> 政策。

預設值 請參閱下方的「Default Policy」分頁
是否必要 必填
類型 類型
父項元素 不適用
子元素 <CloudLogging>
<Syslog>
<logLevel>

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

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails. See also:
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

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

欄位名稱 欄位說明
CloudLogging

設定要記錄至 Cloud Logging 的訊息。

Syslog

設定要記錄至 syslog 的訊息。

範例

CloudLogging

<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 元素包含流程變數

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

當使用者以 message.queryparam.key = "fruit"message.queryparam.value = "apple" 值呼叫 Proxy 時,產生的記錄項目會是 {"fruit": "apple"}

系統記錄檔

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

在本例中,假設您需要記錄 API 從消費者應用程式收到的每個要求訊息相關資訊。值 3f509b58 代表 loggly 服務專屬的鍵值。如果您有 Loggly 帳戶,請改用 Loggly 金鑰。系統會在產生的記錄訊息中填入四個值:與交易相關聯的機構、API 代理程式和環境名稱,以及要求訊息中查詢參數的值。時間戳記的格式會類似 230704-13:42:17.376,具體取決於 DateFormat 元素中指定的格式。

透過 TLS/SSL 傳送 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>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

您可以新增 <SSLInfo> 區塊,透過 TLS/SSL 將訊息傳送至第三方訊息記錄服務供應商。

子元素參照

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

<CloudLogging>

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

欄位名稱 是否必要 說明
LogName 記錄的名稱。記錄名稱的格式應為 projects/{PROJECT_ID}/logs/{LOG_ID}。您可以使用變數取代 {PROJECT_ID}{LOG_ID}
Message

要記錄的訊息。訊息含有屬性 contentType,其值可分別為 text/plainapplication/json,分別代表文字和 JSON 訊息。請參閱範例

Label 要附加至記錄訊息的標籤 (如有)。這些值會以鍵/值組合的形式呈現,如下所示:
<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>
ResourceType 否 (預設為全域) 代表產生記錄的受控資源。

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 等公開記錄管理服務。請參閱「設定第三方記錄管理服務」。

欄位名稱 是否必要 欄位說明
Message

要記錄的訊息。訊息含有屬性 contentType,其值可分別為 text/plainapplication/json,分別代表文字和 JSON 訊息。請參閱範例

Host 應傳送 syslog 的伺服器主機名稱或 IP 位址。如果未加入這個元素,預設值為 localhost。
Port 執行 syslog 的通訊埠。如果未納入此元素,預設值為 514。
Protocol TCP 或 UDP (預設)。雖然 UDP 效能較佳,但 TCP 通訊協定可確保訊息記錄會傳送至 syslog 伺服器。如要透過 TLS/SSL 傳送 Syslog 訊息,則僅支援 TCP。
FormatMessage 否,但您必須使用 <FormatMessage>true</FormatMessage> 才能搭配 Loggly 使用。

truefalse (預設)

您可以使用這個元素控制 Apigee 產生的內容格式,並將該格式置於訊息前端。如果設為 True,系統會在 syslog 訊息前方加上固定數量的字元,讓您從訊息中篩除該資訊。以下是固定格式的範例:

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee - - - Message starts here

Apigee 產生的資訊包括:

  • <14> - 根據訊息的記錄層級和設施層級,計算出優先順序分數 (請參閱 Syslog 通訊協定)。
  • 1 - 目前的 syslog 版本。
  • 日期 (含世界標準時間偏差) (世界標準時間 = +0000)。
  • 訊息處理器 UUID。
  • 「Apigee - - -」

如果設為 false (預設值),系統不會在訊息前方加上這些固定字元。

PayloadOnly

truefalse (預設)

這個元素會將 Apigee 產生的訊息格式設為僅包含 syslog 訊息的內容,而非 FormatMessage 指定的開頭字元。

如果未加入此元素或留空,預設值為 false

請參閱 FormatMessage

DateFormat

用於設定每個記錄訊息時間戳記格式的格式範本字串。根據預設,Apigee 會使用 yyyy-MM-dd'T'HH:mm:ss.SSSZJava 的 SimpleDateFormat 類別說明文件中說明瞭這個範本的行為。根據這個定義,格式字串中的 yyyy 會替換成 4 位數的年份,MM 會替換成 2 位數的月份數字,依此類推。

SSLInfo

可讓您透過 SSL/TLS 記錄訊息。搭配子元素 <Enabled>true</Enabled> 使用。

如果未納入此元素或留空,預設值為 false (不使用 TLS/SSL)。

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

您可以按照在 TargetEndpoint 上設定 <SSLInfo> 標記的方式設定,包括啟用雙向 TLS/SSL,如 API proxy 設定參考資料所述。僅支援 TCP 通訊協定。


<logLevel>

<logLevel> 元素的有效值為:INFO (預設)、ALERTWARNERROR

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

如果您使用 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 元素。

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

錯誤參考資料

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

執行階段錯誤

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

錯誤代碼 HTTP 狀態 原因
steps.messagelogging.StepDefinitionExecutionFailed 500 請參閱錯誤字串。
steps.messagelogging.InvalidGoogleCloudLogName 500 如果 LogName 的評估結果不是有效的格式 (projects/{project}/logs/{logid}),就會擲回此錯誤。
steps.messagelogging.InvalidJsonMessage 500 如果您選擇將 contentType 屬性值設為 application/json,但實際訊息值並非有效的 JSON 字串,系統就會擲回此錯誤。
steps.messagelogging.TooManyPendingLoggingRequest 500 如果有超過 2500 個待處理的請求尚未寫入 Cloud Logging,系統就會擲回這個錯誤。每個 Apigee 執行階段 Pod 的限制為 2500。舉例來說,如果流量會分配至兩個 Apigee 執行階段 Pod 的執行個體,則有效限制為 5000 個要求。
-

部署錯誤

部署含有這項政策的 Proxy 時,可能會發生這些錯誤。

錯誤名稱 原因 修正
InvalidProtocol 如果 <Protocol> 元素中指定的通訊協定無效,部署 MessageLogging 政策可能會失敗,並顯示這項錯誤。有效的通訊協定為 TCP 和 UDP。如要透過 TLS/SSL 傳送 Syslog 訊息,則僅支援 TCP。
InvalidPort 如果 <Port> 元素中未指定埠號碼,或該埠號碼無效,則部署 MessageLogging 政策可能會失敗,並顯示這項錯誤。通訊埠號碼必須是大於零的整數。

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

變數 地點 範例
fault.name="fault_name" fault_name 是錯誤名稱,如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。 fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name 是擲回錯誤的政策的使用者指定名稱。 messagelogging.ML-LogMessages.failed = true

錯誤回應範例

{  
   "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

相關主題