SkyWalking【三、traceId链路日志】

在 Spring Boot 中集成 SkyWalking 的 TraceId 打印，主要有三种方式。

方式一：使用 %tid 占位符（官方推荐）

这是 SkyWalking 官方推荐的方式。它通过替换 Logback 的 Layout 类来实现，功能最完整，但侵入性稍强。

引入 Maven 依赖

确保 pom.xml 中引入了与 Agent 版本一致的 Logback 工具包，且不要指定 。

org.apache.skywalking
apm-toolkit-logback-1.x
9.7.0

配置 logback-spring.xml

关键点：必须使用 LayoutWrappingEncoder 并指定 SkyWalking 的 TraceIdPatternLogbackLayout 类。

%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} - %msg%n

效果与说明
有链路时：%tid 会被替换为实际的 TraceId，例如 [a1b2c3d4e5f6]。
无链路时：%tid 会输出为 TID: N/A，不会报错，不影响正常日志打印。
高级用法：该 Layout 还支持 %sw_ctx 占位符，可以输出完整的 SkyWalking 上下文信息（如服务名、实例ID、SpanId等）。

方式二：使用 %X{tid} 占位符（侵入性小）

如果你不想替换整个 Logback Layout，或者项目已有非常复杂的日志格式，可以使用这种方式。它利用 SkyWalking Agent 自动将 TraceId 注入到 MDC 的 tid 键中。在 Spring Boot 中打印 MDC 自定义内容，核心语法是 %X{key}。
在 Logback 的 中，使用 %X{你的MDC键名} 即可获取对应值。

• 有值时：输出实际内容
• 无值时：输出空字符串
  设置默认值：使用 %X{key:-默认值} 语法

引入 Maven 依赖

与方式一相同，仍需引入 apm-toolkit-logback-1.x 依赖。

配置 logback-spring.xml

关键点：使用标准的 Logback 配置，在 中直接使用 %X{tid} 即可。

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <!-- 核心：使用标准的 PatternLayout，通过 %X{tid} 从 MDC 获取 -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{tid}] [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

效果与说明:

• 有链路时：%X{tid} 会输出实际的 TraceId。
• 无链路时：%X{tid} 会输出为空字符串。如果希望无链路时显示默认值，可以使用 %X{tid:-N/A} 语法。
  优势：完全兼容原有的 Logback 配置，无需改动 Layout 类，适合已有复杂日志格式的项目。

方式三：手动将traceId放入MDC进行打印

引入依赖

同之前的依赖相同

修改代码

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

public class SkyTraceUtil {
    // 从skywalking的上下文中获取traceIdID，然后放入MDC中
    public static void putTraceToMdc() {
        String traceId = TraceContext.traceId();
        MDC.put("traceId", traceId);
    }
    // 结束后清除上下文
    public static void clearMdc() {
        MDC.remove("traceId");
    }
}

配置

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <!-- 核心：使用标准的 PatternLayout，通过 %X{traceId} 从 MDC 获取 -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{traceId}] [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

💡 核心注意事项

• %X{tid}：从 MDC 中读取，依赖 Agent 的自动注入。
• %tid：是 SkyWalking 专属 Layout 提供的占位符，它不依赖 MDC，而是直接从 Agent 的 TraceContext 中获取。即使 MDC 中没有 tid，只要 Agent 处于激活状态，%tid 也能正确输出 TraceId 或 TID: N/A。
• 版本一致性：apm-toolkit-logback-1.x 的 Maven 依赖版本必须与 skywalking-agent.jar 的版本严格一致，否则可能导致功能异常或启动失败。
• Agent 必须挂载：无论使用哪种方式，都必须通过 -javaagent 参数启动应用。如果未挂载 Agent，方式一会输出 TID: N/A，方式二会输出空值，但都不会导致应用启动失败。