Antipattern:在 API Proxy 中多次叫用 MessageLogging 政策

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

Apigee Edge 的 MessageLogging 政策可讓 API Proxy 開發人員將自訂訊息記錄到 syslog 或磁碟 (僅限 Private Cloud 的 Edge)。系統會記錄任何與 API 要求相關的重要資訊,例如輸入參數、要求酬載、回應代碼、錯誤訊息 (如有) 等等,以供日後參考或偵錯。雖然政策使用背景程序執行記錄,但使用政策仍會有註意事項。

反模式

MessageLogging 政策可讓您有效率地取得 API 要求的相關資訊,並對 API 要求發生的任何問題進行偵錯。不過,如果多次使用相同的 MessageLogging 政策,或是在相同 API Proxy 以外的流程中將多項 MessageLogging 政策記錄資料分塊在區塊中,則可能會造成負面影響。這是因為 Apigee Edge 會針對 MessageLogging 政策,開啟與外部系統記錄檔伺服器的連線。 如果政策透過 TCP 使用傳輸層安全標準 (TLS),建立傳輸層安全標準 (TLS) 連線會產生額外的負荷。

讓我們透過範例 API Proxy 來說明這一點。

API Proxy

在以下範例中,名為「LogRequestInfo」的 MessageLogging 政策會放入要求流程中,並將另一個名為「LogResponseInfo」的 MessageLogging 政策新增至回應流程。兩者都位於 ProxyEndpoint PreFlow 中。API Proxy 收到要求後,LogRequestInfo 政策會在背景中執行,而 LogResponseInfo 政策會在 Proxy 收到目標伺服器的回應「之後」執行,但在 Proxy 傳回 API 用戶端的回應「之前」。由於可能有兩個傳輸層安全標準 (TLS) 連線,因此這會使用額外的系統資源。

此外,有一個名為「LogErrorInfo」的 MessageLogging 政策,只有在 API Proxy 執行期間發生錯誤時才會執行。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
  ...
<FaultRules>
    <FaultRule name="fault-logging">
        <Step>
            <Name>LogErrorInfo</Name>
        </Step>
    </FaultRule>
</FaultRules>
<PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>LogRequestInfo</Name>
      </Step>
    </Request>
  </PreFlow>
  <PreFlow name="PreFlow">
    <Response>
      <Step>
        <Name>LogResponseInfo</Name>
      </Step>
    </Response>
  </PreFlow>
  ...
</ProxyEndpoint>

訊息記錄政策

在以下政策設定範例中,系統會透過 TCP 使用傳輸層安全標準 (TLS) 將資料登入第三方記錄伺服器。如果在同一個 API Proxy 中使用多項政策,建立及管理 TLS 連線的負擔可能會佔用額外的系統記憶體和 CPU 週期,導致大規模的效能問題。

LogRequestInfo 政策

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogRequestInfo">
  <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>INFO</logLevel>
</MessageLogging>

LogResponseInfo 政策

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogResponseInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Status: {response.status.code}, Response {response.content}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

LogErrorInfo 政策

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogErrorInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Fault name: {fault.name}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>ERROR</logLevel>
</MessageLogging>

影響程度

  • 在 API Proxy 流程期間,多次連線至記錄檔伺服器,網路負擔增加。
  • 如果系統記錄伺服器速度緩慢或無法處理多個系統記錄呼叫造成的大量磁碟區,就會造成訊息處理器的返回壓力,進而導致要求處理速度變慢,並可能產生高延遲時間或 504 閘道逾時錯誤。
  • 針對使用檔案記錄功能的私人雲端設定,訊息處理器開啟的並行檔案描述元數量增加。
  • 如果 MessageLogging 政策置於 PostClient 流程以外的流程中,系統就可能不會記錄資訊,因為如果在這項政策執行前發生任何失敗,則系統不會執行 MessageLogging 政策。

    在先前的 ProxyEndpoint 範例中,在下列情況下,系統不會記錄相關資訊:

    • 在要求流程中,置於 LogRequestInfo 政策之前的任何政策都會失敗。
    • 如果目標伺服器發生任何錯誤 (HTTP 4XX、5XX),在這種情況下,如果未傳回成功的回應,則系統不會執行 LogResponseInfo 政策。

    在這兩種情況下,系統都會執行 LogErrorInfo 政策,並僅記錄錯誤相關資訊。

最佳做法

  • 使用「ExtractVariables」政策或「JavaScript 政策」,設定要記錄的所有流程變數,以便用於 MessageLogging 政策。
  • 使用單一 MessageLogging 政策來記錄 PostClientFlow 中的所有必要資料,系統會無條件執行。
  • 使用 UDP 通訊協定,不必要求保證訊息傳送至系統記錄伺服器,而且不一定要使用 TLS/SSL。

MessageLogging 政策將與實際的 API 功能 (包括錯誤處理) 分離。因此,在要求/回應處理之外的 PostClientFlow 中叫用資料,表示無論 API 是否失敗,它一律會記錄資料。

以下是在 PostClientFlow 中叫用 MessageLogging 政策的範例:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 ...
<PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>LogInfo</Name>
            </Step>
        </Response>
</PostClientFlow>
 ...

以下為 MessageLogging 政策的 LogInfo 範例,該政策記錄了所有資料:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {woeid} Status: {weather.response.code}, Response {weather.response}, Fault: {fault.name:None}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

由於在錯誤流程後的 PostClientFlow 中不提供回應變數,因此請務必透過「擷取變數」或 JavaScript 政策明確設定 woeidweather.response* 變數。

其他資訊