Logs 关联：Trace ID 注入

欢迎回到第 9 章的学习。在上一节，我们学习了 Metrics 收集。现在我们要学习 Logs 关联：Trace ID 注入，这对于关联日志和追踪非常重要。

本节将学习：Logback 配置、MDC 使用、日志格式化、以及 Trace ID 关联。

Logback 配置

Logback 是什么？ Logback 是 Spring Boot 默认的日志框架。它支持灵活的配置，可以自定义日志格式。

如何配置 Logback 支持 Trace ID 注入呢？

第一步：创建 logback-spring.xml 文件。 在

src/main/resources/

logback-spring.xml

第二步：配置日志格式。 使用

<pattern>

%X{traceId}

%X{spanId}

第三步：配置 OpenTelemetry Appender（可选）。 如果需要，可以配置 OpenTelemetry 的 logback appender，自动注入 Trace ID。

配置代码：

文件路径：

src/main/resources/logback-spring.xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <springProfile name="!prod">
        <!-- Development environment: standard format -->
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level [traceId=%X{traceId}, spanId=%X{spanId}] %logger{36} - %msg%n</pattern>
            </encoder>
        </appender>
        <root level="INFO">
            <appender-ref ref="CONSOLE" />
        </root>
    </springProfile>
    
    <springProfile name="prod">
        <!-- Production environment：JSON formats -->
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder class="net.logstash.logback.encoder.LogstashEncoder">
                <includeMdcKeyName>traceId</includeMdcKeyName>
                <includeMdcKeyName>spanId</includeMdcKeyName>
            </encoder>
        </appender>
        <root level="INFO">
            <appender-ref ref="CONSOLE" />
        </root>
    </springProfile>
</configuration>

MDC 使用

MDC 是什么？ MDC（Mapped Diagnostic Context）是 Logback 提供的上下文机制。OpenTelemetry 会自动将 Trace ID 注入到 MDC 中，我们可以在日志格式中使用。

如何手动使用 MDC 呢？

第一步：在代码中使用 MDC。 使用

MDC.put("key", "value")

第二步：在日志格式中引用。 在日志格式中使用

%X{key}

代码示例：

import org.slf4j.MDC;

public Order createOrder(OrderRequest request) {
    MDC.put("user.id", request.getUserId());
    MDC.put("order.type", "new");
    
    // Business logic
    
    MDC.clear();
}

日志格式化

日志格式化是什么？ 日志格式化用于配置日志输出格式，在日志中包含 Trace ID 和 Span ID。

如何配置日志格式呢？

第一步：配置 pattern layout。 在 logback-spring.xml 中配置

<pattern>

第二步：包含 Trace ID 和 Span ID。 包含时间戳、级别、Trace ID、Span ID、消息等。

示例格式：

%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level [traceId=%X{traceId}, spanId=%X{spanId}] %logger{36} - %msg%n

Trace ID 关联

Trace ID 关联是什么？ Trace ID 关联用于通过 Trace ID 关联查看日志、指标和追踪数据，实现完整的可观察性。

如何实现 Trace ID 关联呢？

第一步：启动应用并发送请求。 启动应用，发送一个 HTTP 请求。

第二步：在日志中找到 Trace ID。 在日志中找到 Trace ID。

第三步：在 Grafana 中查询追踪数据。 在 Grafana Explore 中使用 Trace ID 查询追踪数据。

第四步：在 Grafana 中查询日志数据。 在 Grafana Explore 中使用 Trace ID 查询日志数据。

第五步：查看关联的指标数据。 在 Grafana Dashboard 中查看关联的指标数据。

通过 Trace ID，我们可以在 Grafana 中关联查看日志、指标和追踪数据，实现完整的可观察性。

本节小结

在本节中，我们学习了 Logs 关联：Trace ID 注入：

第一个是 Logback 配置。 创建 logback-spring.xml 文件，配置日志格式，包含 Trace ID 和 Span ID。

第二个是 MDC 使用。 OpenTelemetry 自动将 Trace ID 注入到 MDC，可以手动使用 MDC 添加自定义上下文。

第三个是日志格式化。 配置日志格式，在日志输出中包含 Trace ID 和 Span ID。

第四个是 Trace ID 关联。 通过 Trace ID 关联查看日志、指标和追踪数据，实现完整的可观察性。

Logs 关联总结： Logs 关联包括 Logback 配置（日志格式配置）、MDC 使用（Trace ID 注入）、日志格式化（包含 Trace ID）、Trace ID 关联（三维关联查询）。这些功能组合在一起，构成了完整的日志关联能力。

这就是 Logs 关联：Trace ID 注入。掌握这些功能，可以关联查看日志、指标和追踪数据。

在下一节，我们将学习完整示例：订单服务实现。学习如何构建完整的后端服务。