您正在查看 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 政策類型的常見用途為登入系統記錄檔帳戶。針對 Syslog 設定之後,API Proxy 會將記錄訊息從 Apigee Edge 轉送至遠端系統記錄檔伺服器。您必須有可用的系統記錄伺服器。如果不支援,則會提供公開記錄管理服務,例如 Splunk、Sumo Logic 和 Loggly。請參閱設定第三方記錄管理服務。
舉例來說,假設您需要記錄 API 從消費者應用程式收到的每則要求訊息的相關資訊。3f509b58
值代表 Loggly 服務專屬的鍵值。如果您有記錄帳戶,請更換記錄金鑰。產生的記錄訊息將填入四個值:與交易相關聯的機構、API Proxy 和環境名稱,以及要求訊息中的查詢參數值。
如果您有 Edge for Private Cloud 部署,您也可以將記錄訊息寫入檔案。
傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 的系統記錄檔
<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>
只要新增 <SSLInfo>
區塊,即可透過 TLS/SSL 傳送訊息給第三方訊息記錄服務供應商。
檔案旋轉:大小
<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 政策類型。
欄位名稱 | 欄位說明 | |
---|---|---|
本機檔案目的地。(Edge 僅支援 Private Cloud 部署項目的檔案記錄功能)。如要瞭解檔案儲存位置,請參閱適用於 Private Cloud 的 Edge 記錄檔位置。 |
Message |
建構要傳送至記錄檔的訊息,結合文字與變數來擷取所需資訊。請參閱範例。 |
FileName |
記錄訊息的記錄檔名稱。 | |
FileRotationOptions |
||
rotateFileOnStartup |
屬性。有效值: 如果設為 True,則每次訊息引擎重新啟動時,記錄檔都會輪替。 |
|
FileRotationType |
指定記錄檔的輪替政策 (size 或 time )。 |
|
MaxFileSizeInMB |
(選取 size 做為旋轉類型時)
指定記錄檔的大小,這會觸發伺服器將記錄訊息移至個別檔案。記錄檔達到指定大小後,伺服器會重新命名目前的記錄檔。 |
|
RotationFrequency |
(選取 time 做為輪替類型時) 指定觸發伺服器將記錄訊息移至個別檔案的時間 (以分鐘為單位)。過了指定的間隔後,系統會重新命名目前的記錄檔。 |
|
MaxFilesToRetain |
指定要在輪替設定內容中保留的檔案數量上限。預設值為 8。 如果指定零 (0),記錄檔會無限期保留,但仍會套用檔案旋轉設定,但系統不會刪除或重新命名任何檔案。因此,為了避免日後發生完整磁碟錯誤,請將這個值設為大於零的值,或是實作一般的自動化系統,以清除或封存較舊的保留記錄檔。 |
|
BufferMessage |
如果您的 Proxy 已啟用 HTTP 串流,要求/回應訊息就不會緩衝。如要記錄需要剖析流程訊息的內容,請將 BufferMessage 設為 true。如需範例,請參閱「已啟用串流功能」的範例分頁。預設值:false |
|
系統記錄檔目的地。如要將 syslog 傳送至 Splunk、Sumo Logic 或 Loggly,請參閱「設定第三方記錄管理服務」。 |
Message |
建構要傳送至系統記錄檔的訊息,結合文字與變數來擷取所需資訊。請參閱範例。 注意:在錯誤流程後的 PostClientFlow 中無法使用回應變數。使用訊息變數記錄錯誤和成功情況的回應資訊。另請參閱「使用注意事項」。 |
Host |
應傳送系統記錄檔的伺服器主機名稱或 IP 位址。如果您沒有加入這個元素,預設值為 localhost。 | |
Port |
執行系統記錄檔的通訊埠。如果您沒有加入這個元素,預設值為 514。 | |
Protocol |
TCP 或 UDP (預設)。雖然 UDP 的效能較高,但 TCP 通訊協定保證會將訊息記錄傳送至系統記錄伺服器。如果是透過傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 傳送系統記錄檔訊息,僅支援 TCP。 | |
FormatMessage |
選用,但必須設定 這個元素可讓您控製附加在訊息的 Apigee 產生內容的格式。如果設為 True,系統記錄訊息前面會加上固定的字元數,讓您可以從訊息中篩除該資訊。以下是固定格式的範例:
Apigee 產生的資訊包括:
如果設為 false (預設值),訊息前方不會加上這些固定字元。 |
|
PayloadOnly |
這個元素會將 Apigee 產生的訊息格式設為僅包含系統記錄檔訊息的主體,不含 FormatMessage 指定的前置字元。 如果您未提供這個元素或留空,預設值為 請參閱 FormatMessage。 |
|
DateFormat |
選用。 格式化範本字串,用於設定每個記錄訊息的時間戳記格式。
Apigee 預設使用 |
|
SSLInfo |
讓您透過 SSL/TLS 記錄訊息。與子元素 如果您沒有加入這個元素或將這個元素留空,預設值為 false (未使用 TLS/SSL)。 <SSLInfo> <Enabled>true</Enabled> </SSLInfo> 您可以比照在 TargetEndpoint 上設定的方式設定 <SSLInfo> 標記,包括啟用雙向 TLS/SSL,如 API Proxy 設定參考資料所述。僅支援 TCP 通訊協定。 |
|
logLevel |
選用。 有效值: 設定要納入訊息記錄的特定資訊層級。 如果您使用 |
結構定義
使用注意事項
將 MessageLogging 政策附加至 API Proxy 流程時,請考慮將其放在 ProxyEndpoint 回應的 Proxy 端點回應中,也就是名為 PostClientFlow 的特殊流程中。將回應傳送至要求端用戶端後,PostClientFlow 就會執行,確保所有指標都能記錄下來。如要進一步瞭解如何使用 PostClientFlow,請參閱 API Proxy 設定參考資料。
PostClientFlow 有以下兩種特殊之處:
- 該函式只會在回應流程中執行。
- 這是 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
如何變更格式:
- 在編輯器中開啟 message-processor.properties 檔案。如果檔案不存在,請建立檔案:
> vi /opt/apigee/customer/application/message-processor.properties - 視需要設定屬性:
conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ - 儲存變更。
- 請確認您的屬性檔案為「apigee」使用者擁有:
> chown apigee:apigee:apigee /opt/apigee/customer/application/message-processor.properties - 重新啟動邊緣訊息處理器:
> /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}
的格式。
如何設定這些屬性:
- 在編輯器中開啟 message-processor.properties 檔案。如果檔案不存在,請建立檔案:
> vi /opt/apigee/customer/application/message-processor.properties - 視需要設定屬性:
conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages - 儲存變更。
- 請確認您的屬性檔案為「apigee」使用者擁有:
> chown apigee:apigee:apigee /opt/apigee/customer/application/message-processor.properties - 重新啟動 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 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 |
---|---|---|
steps.messagelogging.StepDefinitionExecutionFailed |
500 | 查看錯誤字串。 |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
InvalidProtocol |
如果 <Protocol> 元素中指定的通訊協定無效,MessageLogging 政策的部署作業可能會失敗。有效的通訊協定為 TCP 和 UDP。如果是透過 TLS/SSL 傳送系統記錄訊息,則僅支援 TCP。 |
build |
InvalidPort |
如果 <Port> 元素中未指定通訊埠號碼,或是通訊埠號碼無效,MessageLogging 政策的部署作業可能會失敗。通訊埠編號必須為大於零的整數。 |
build |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
錯誤回應範例
{ "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 公開的變數:變數參考資料