View a markdown version of this page

啟用追蹤與日誌的關聯 - Amazon CloudWatch
追蹤日誌關聯設定範例

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

啟用追蹤與日誌的關聯

可以在 Application Signals 中啟用追蹤與日誌的關聯。這會自動將追蹤 ID 和範圍 ID 注入相關的應用程式日誌。然後，當您在 Application Signals 主控台中開啟追蹤詳細資訊頁面時，與當前追蹤關聯的相關日誌條目 (如有) 會自動顯示於頁面底部。

例如，假設您注意到延遲圖表出現突發性飆升。可以選擇圖表上的點，以載入該時間點的診斷資訊。然後，可以選擇相關的追蹤以取得更多資訊。當您檢視追蹤資訊時，可以向下捲動以查看與追蹤相關聯的日誌。這些日誌可能揭示與導致延遲飆升問題相關的模式或錯誤代碼。

在設定追蹤日誌相互關聯之前檢測您的應用程式

在設定追蹤日誌相互關聯之前，您的應用程式必須已針對 Application Signals 進行檢測。Application Signals 檢測是在執行時間填入 trace_id、 span_id和 trace_flags MDC 值。如果沒有檢測，這些值會保持空白 （例如 trace_id=)，而且相互關聯無法運作。

為實現追蹤日誌關聯，Application Signals 依賴以下要素：

OpenTelemetry 社群提供所有這些檢測。Application Signals 會使用它們將追蹤內容 (例如追蹤 ID 與範圍 ID) 注入應用程式日誌。若要啟用此功能，必須手動變更記錄組態以啟用自動檢測。

視執行應用程式的架構而定，除遵循本節中的步驟之外，可能還必須設定環境變數來啟用追蹤日誌關聯。

  • 在 Amazon EKS 上，不需要額外的環境變數。您仍然必須設定記錄輸出，如下列範例所述，而且您的記錄器必須寫入 stdout，以便 Container Insights 可以收集日誌。

  • 在 Amazon ECS 上，不需要額外的環境變數。您仍然必須設定記錄輸出，如下列範例所述，而且您的記錄器必須寫入 stdout，以便 Container Insights 可以收集日誌。

  • 在 Amazon EC2 上，請參閱 步驟 3：檢測您的應用程式並啟動它 程序中的步驟 4。

OpenTelemetry Container Insights 不會自動啟用追蹤日誌相互關聯

啟用 OpenTelemetry 型 Container Insights 日誌收集路徑 （例如，透過 CloudWatch 可觀測性 EKS 附加元件) 會收集容器日誌並將其運送到 CloudWatch Logs，但不會檢測您的應用程式以取得 Application Signals 或將追蹤內容注入這些日誌。若要將追蹤與日誌建立關聯，您必須個別啟用 Application Signals 檢測，並如本頁所述設定記錄模式。

啟用追蹤日誌關聯後，當您開啟追蹤詳細資訊頁面時，包含相同追蹤 ID 的任何日誌項目會自動出現在頁面底部。透過追蹤日誌關聯，您可以快速從追蹤移至相關的應用程式日誌，而無需手動搜尋。

追蹤日誌關聯設定範例

本節包含在多個環境中設定追蹤日誌關聯的範例。

適用於 Java 的 Spring Boot

假設您在名為 custom-app 的資料夾中有 Spring Boot 應用程式。應用程式組態通常是名為 custom-app/src/main/resources/application.yml 的 YAML 檔案，可能如下所示：

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...

若要啟用追蹤日誌關聯，新增下列記錄組態。

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...    

logging:
  pattern:
    level: trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p
Spring Boot 和 XML 組態是替代方案

以下各節中顯示的 Spring Boot application.yml(logging.pattern.level) 方法和 Logback/Log4j2/Log4j XML 組態方法是替代方法。使用其中一個，而非兩者。如果您在 中設定模式application.yml，Spring Boot 的預設 Logback 組態會自動取得，而且logback.xml不需要個別設定。

EKS 和 ECS：將日誌寫入 stdout

Container Insights 會從容器的 stdout/stderr 收集日誌，而不是從容器內寫入的檔案收集日誌。將記錄器設定為寫入 主控台 (stdout)。FileAppender 寫入 等檔案app.log會產生正確的追蹤標記行，但不會收集它們，也不會在追蹤詳細資訊頁面上顯示關聯。如果您必須登入檔案，您還需要將檔案 （例如讀取共用磁碟區的附屬收集器） 運送到此頁面範圍之外。

適用於 Java 的 Logback

在記錄組態 (例如 logback.xml) 中，將追蹤內容 trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p 插入編碼器的 pattern。例如，以下組態會在日誌訊息之前加上追蹤內容。

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
  <encoder> 
    <pattern>trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n</pattern> 
  </encoder>
</appender>

如需 Logback 中編碼器的詳細資訊，請參閱 Logback 文件中的編碼器。

適用於 Java 的 Log4j2

在記錄組態 (例如 log4j2.xml) 中，將追蹤內容 trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p 插入 PatternLayout。例如，以下組態會在日誌訊息之前加上追蹤內容。

<Appenders>
  <Console name="CONSOLE" target="SYSTEM_OUT">
    <PatternLayout pattern="trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n"/>
  </Console>
</Appenders>

如需 Log4j2 中模式配置的詳細資訊，請參閱 Log4j2 文件中的模式配置。

適用於 Java 的 Log4j

在記錄組態 (例如 log4j.xml) 中，將追蹤內容 trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %5p 插入 PatternLayout。例如，以下組態會在日誌訊息之前加上追蹤內容。

<appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
  <layout class="org.apache.log4j.PatternLayout">
    <param name="ConversionPattern" value="trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} %5p - %m%n"/>
  </layout>
</appender>

如需 Log4j 中模式配置的詳細資訊，請參閱 Log4j 文件中的類別模式配置。

Python

在執行應用程式時，將環境變數 OTEL_PYTHON_LOG_CORRELATION 設定為 true。如需詳細資訊，請參閱 Python OpenTelemetry 文件中的啟用追蹤內容注入。

Node.js

如需有關在 Node.js 中為支援的日誌記錄庫啟用追蹤內容注入的詳細資訊，請參閱 Pino、Winston 或 Bunyan 自動檢測的 NPM 使用文件。

驗證設定

重新部署應用程式後，確認日誌行現在顯示已填入 trace_id（例如，透過執行 kubectl logs pod-name)。然後在 Application Signals 主控台中開啟追蹤詳細資訊頁面，並確認相關的日誌項目出現在頁面底部。

在 Amazon EKS 上，日誌會寫入 Container Insights 應用程式日誌群組 (/aws/containerinsights/cluster-name/application或在啟用 OpenTelemetry Container Insights 日誌路徑/aws/otel/containerinsights/cluster-name/application時）。