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> 政策。

預設值	請參閱下方的「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>

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

屬性	預設	是否必要？	說明
name	不適用	必要	政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError	false	選用	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
enabled	是	選用	設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async	false	已淘汰	此屬性已淘汰。

下表概略說明 <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 元素中指定的格式。

注意： Host 和 Port 元素無法參照變數。必須包含靜態值。

透過 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。

注意：如要使用 <CloudLogging>，您必須為 Google Cloud 專案啟用 Cloud Logging API。如要為 Google Cloud 專案啟用 API，請參閱「啟用及停用服務」。MessageLogging 政策的 <CloudLogging> 元素適用於 Apigee 和 Apigee Hybrid 1.7.0 以上版本。

欄位名稱	是否必要	說明
LogName	是	記錄的名稱。記錄名稱的格式應為 projects/{PROJECT_ID}/logs/{LOG_ID}。您可以使用變數取代 {PROJECT_ID} 和 {LOG_ID}。 注意：LogName 會指定要傳送記錄項目的 Cloud Logging 記錄資源名稱。透過使用變數，MessageLogging 政策可讓您為每個 LogName 項目動態插入不同的專屬名稱值；不過，我們不建議採用這種做法，並建議您不要動態建立專屬記錄名稱，且這些名稱的值會因要求而異，因為這可能會導致高秩數問題。建議您改為使用固定的名稱組合，為 LogName 指定固定且有意義的名稱。
Message	是	要記錄的訊息。訊息含有屬性 contentType，其值可分別為 text/plain 或 application/json，分別代表文字和 JSON 訊息。請參閱範例。 注意：在 PostClientFlow 中，如果有錯誤流程，就無法使用回應變數。使用 message。記錄錯誤和成功情況的回應資訊。另請參閱使用說明。 注意：<Message> 元素支援動態字串替換功能，稱為 訊息範本。
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/plain 或 application/json，分別代表文字和 JSON 訊息。請參閱範例。 注意：<Message>> 元素支援稱為「 訊息模板」的動態字串替換功能， 注意：在發生錯誤流程後，PostClientFlow 中不會提供回應變數，使用 message。記錄錯誤和成功情況的回應資訊。另請參閱使用說明。
Host	否	應傳送 syslog 的伺服器主機名稱或 IP 位址。如果未加入這個元素，預設值為 localhost。
Port	否	執行 syslog 的通訊埠。如果未納入此元素，預設值為 514。
Protocol	否	TCP 或 UDP (預設)。雖然 UDP 效能較佳，但 TCP 通訊協定可確保訊息記錄會傳送至 syslog 伺服器。如要透過 TLS/SSL 傳送 Syslog 訊息，則僅支援 TCP。
FormatMessage	否，但您必須使用 <FormatMessage>true</FormatMessage> 才能搭配 Loggly 使用。	true 或 false (預設) 您可以使用這個元素控制 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 (預設值)，系統不會在訊息前方加上這些固定字元。 注意：如果您設定 <FormatMessage>false</FormatMessage>，記錄訊息仍會包含優先順序分數和日期。如要將記錄訊息格式化為僅包含郵件內文，請設定 <PayloadOnly>true</PayloadOnly>。 請參閱「PayloadOnly」PayloadOnly。
PayloadOnly	否	true 或 false (預設) 這個元素會將 Apigee 產生的訊息格式設為僅包含 syslog 訊息的內容，而非 FormatMessage 指定的開頭字元。 如果未加入此元素或留空，預設值為 false。 請參閱 FormatMessage。 注意： 設定 <PayloadOnly>true</PayloadOnly> 會覆寫 FormatMessage 的設定。
DateFormat	否	用於設定每個記錄訊息時間戳記格式的格式範本字串。根據預設，Apigee 會使用 yyyy-MM-dd'T'HH:mm:ss.SSSZ。Java 的 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 (預設)、ALERT、WARN、ERROR。

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

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

使用須知

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

注意：請注意，一旦處理程序進入錯誤狀態，PostClientFlow 就無法使用 response 流程變數。您可以改用 message 變數，在 PostClientFlow 的 MessageLogging 政策中設定值，確保在錯誤狀態為先前內容時，這些值會設好。如需更多資訊和範例，請參閱「流程變數參考資料」。

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」政策會將記憶體中的記錄訊息寫入緩衝區。訊息記錄器會從緩衝區讀取訊息，然後寫入您設定的目的地。每個目的地都有自己的緩衝區。

注意： Proxy 呼叫在記錄失敗時會成功

由於訊息記錄會先寫入緩衝區，因此即使訊息記錄最終失敗 (例如，如果目的地連線失敗)，API Proxy 仍會繼續執行。

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

• 使用 <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)。

注意：Apigee 中的回應訊息變數無法透過錯誤流程使用。如果先前的流程是錯誤流程，則 PostClientFlow 也不會提供這些變數。如果您想記錄 PostClientFlow 的回應資訊，請使用 message。無論是否發生錯誤，您都可以使用這個物件從回應中取得標頭和其他資訊。詳情請參閱「流程變數參考資料」一文，瞭解相關範例。

訊息範本中變數的預設值

您可以為訊息範本中的每個變數分別指定預設值。舉例來說，如果無法解析變數 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 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼	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 政策可能會失敗，並顯示這項錯誤。通訊埠號碼必須是大於零的整數。

錯誤變數

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

注意： 記錄失敗時，Proxy 呼叫會成功

政策錯誤和訊息記錄錯誤有所不同。只有在政策本身失敗時，才會填入這裡的流程變數，而非在訊息記錄失敗時。由於訊息記錄會先寫入緩衝區，因此即使訊息記錄最終失敗 (例如，如果與外部 syslog 供應器的連線失敗)，API 代理程式仍會繼續執行。請務必定期檢查記錄檔，確保記錄功能正常運作。

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

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

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

注意： 記錄失敗時，Proxy 呼叫會成功

政策錯誤和訊息記錄錯誤有所不同。只有在政策本身失敗時，才會填入這裡的流程變數，而非在訊息記錄失敗時。由於訊息記錄會先寫入緩衝區，因此即使訊息記錄最終失敗 (例如，如果外部 syslog 供應器發生連線失敗)，API 代理程式仍會繼續執行。請務必定期查看記錄檔，確保記錄功能正常運作。

---

相關主題

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