如何在日志中正确打印SkyWalking的traceId？

Question

**问题：** 在使用 SkyWalking 进行分布式链路追踪时，如何在日志中正确打印 traceId，以便与日志系统（如 Logback、Log4j2）集成，实现链路与日志的关联定位？常见方案有哪些？如何避免 traceId 丢失或错乱？

Answer 1

一、背景与问题概述

在微服务架构中，链路追踪（如 SkyWalking）和日志系统（如 Logback、Log4j2）是两个关键的可观测性工具。为了实现链路追踪 ID（traceId）与日志的关联，需要在日志中正确打印 traceId。然而，在实际开发中，traceId 丢失或错乱是常见的问题。

二、SkyWalking 的 traceId 是什么？

SkyWalking 通过全局唯一的 traceId 标识一次完整的分布式请求链路，每个服务调用会生成一个 spanId，形成父子关系。traceId 是链路追踪的核心标识。

• traceId：全局唯一，标识一次请求的完整链路
• spanId：局部唯一，标识一次服务调用
• parentSpanId：标识当前 span 的父级

三、日志系统如何与 traceId 集成？

日志系统如 Logback 和 Log4j2 支持通过 MDC（Mapped Diagnostic Context）机制将 traceId 注入到日志输出中。

日志框架	MDC Key	示例配置
Logback	tid	%X{tid}
Log4j2	traceId	${ctx:traceId}

四、常见集成方案

1. 自动注入方案（推荐）：
   SkyWalking Agent 自动将 traceId 设置到 MDC 中，适用于大多数场景，无需额外编码。
2. 手动注入方案：
   在业务代码中获取当前 traceId 并手动设置到 MDC，适用于复杂异步或跨线程场景。
3. 日志格式统一方案：
   在日志模板中统一添加 traceId 字段，便于日志系统解析和展示。

五、避免 traceId 丢失或错乱的实践

在异步、线程池、消息队列等场景中，traceId 容易丢失或错乱。以下是一些关键措施：

• 使用 Trace ID Context Propagation 机制，确保跨线程传递
• 在异步调用中显式传递 traceId，例如通过消息头或参数
• 使用 TransmittableThreadLocal 替代普通 ThreadLocal，确保线程上下文传递
• 避免日志异步输出导致的上下文污染

六、代码示例：Logback 配置中添加 traceId

<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg %X{tid}%n</pattern>

七、代码示例：手动设置 traceId 到 MDC

import org.apache.skywalking.apm.toolkit.trace.TraceContext;
import org.slf4j.MDC;

public class TraceUtil {
    public static void setTraceIdToMDC() {
        String traceId = TraceContext.traceId();
        MDC.put("tid", traceId);
    }

    public static void clearMDC() {
        MDC.clear();
    }
}

八、流程图：traceId 传递与日志集成流程

graph TD
            A[客户端请求] --> B[网关接收]
            B --> C[生成 traceId]
            C --> D[服务A调用]
            D --> E[服务B调用]
            E --> F[服务C调用]
            B --> G[日志输出]
            D --> G
            E --> G
            F --> G
            G --> H[日志中包含 traceId]
            H --> I[日志系统收集]
            I --> J[SkyWalking 查询日志]

九、常见问题排查指南

• 日志中未打印 traceId：检查 MDC 配置是否正确
• traceId 错乱：检查线程上下文是否被污染
• 异步调用丢失 traceId：检查是否使用 TransmittableThreadLocal
• 日志与链路不一致：检查日志收集系统是否支持 traceId 字段