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 Observability EKS 附加组件），可收集容器日志并将其发送到 CloudWatch Logs，但不会针对 Application Signals 检测应用程序，也不会向这些日志注入跟踪上下文。要将跟踪与日志相关联，必须单独启用 Application Signals 检测，并按照本页所述配置日志记录模式。

启用跟踪日志关联后，当打开跟踪详细信息页面时，任何包含相同跟踪 ID 的日志条目都会自动显示在页面底部。借助跟踪日志关联，无需手动搜索即可快速从跟踪跳转到相关的应用程序日志。

跟踪日志关联设置示例

本节包含在多个环境中设置跟踪日志关联的示例。

Spring Boot for Java

假设您在名为 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）。写入文件（例如 app.log）的 FileAppender 会生成带有正确跟踪标签的行，但这些行不会被收集，也不会以关联形式显示在跟踪详细信息页面上。如果必须将日志记录到文件，则还需要传送该文件（例如，读取共享卷的 sidecar 收集器），这超出本页的范围。

Logback for Java

在日志记录配置（例如 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 文档中的 Encoders。

Log4j2 for Java

在日志记录配置（例如 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 文档中的 Pattern Layout。

Log4j for Java

在日志记录配置（例如 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 文档中的 Class Pattern Layout。

Python

运行应用程序时，将环境变量 OTEL_PYTHON_LOG_CORRELATION 设置为 true。有关更多信息，请参阅 Python OpenTelemetry 文档中的 Enable trace context injection。

Node.js

有关在 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 或 /aws/otel/containerinsights/cluster-name/application（启用 OpenTelemetry Container Insights 日志路径））。