Jaeger Trace MDC

Simple Demo Code

1. 方案概述

1.1 背景与目标

在分布式系统中，跨服务的请求链路追踪是定位问题的关键手段。本方案旨在实现 Jaeger 分布式追踪与 SLF4J MDC（Mapped Diagnostic Context）的深度集成，使得：

日志自动携带 traceId/spanId，便于日志聚合查询
支持跨服务的 trace 上下文传递
在线程池等异步场景下保持 trace 上下文的准确性

1.2 核心价值

问题定位效率提升：通过 traceId 快速关联分布式系统中的所有相关日志
零侵入性：业务代码无需手动管理 MDC，自动注入和清理
线程安全：支持嵌套 Span 和线程池复用场景

2. 架构设计

2.1 整体架构图

┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │ Controller   │───>│  Service     │───>│   DAO        │  │
│  │ (HTTP Entry) │    │ (Business)   │    │ (Database)   │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│         │                    │                    │          │
│         └────────────────────┴────────────────────┘          │
│                              │                                │
├──────────────────────────────┼────────────────────────────────┤
│          Tracing Layer       ▼                                │
│  ┌───────────────────────────────────────────────┐           │
│  │     CustomMDCScopeManager (核心组件)          │           │
│  │  ┌─────────────────────────────────────┐     │           │
│  │  │  ThreadLocal<CustomMDCScope>        │     │           │
│  │  │  - 管理 Scope 生命周期              │     │           │
│  │  │  - 维护 Span 栈                     │     │           │
│  │  └─────────────────────────────────────┘     │           │
│  │                                               │           │
│  │  ┌─────────────────────────────────────┐     │           │
│  │  │  CustomMDCScope (Scope 实现)        │     │           │
│  │  │  - MDC 快照与恢复                   │     │           │
│  │  │  - 支持嵌套 Span                    │     │           │
│  │  └─────────────────────────────────────┘     │           │
│  └───────────────────────────────────────────────┘           │
│                              │                                │
├──────────────────────────────┼────────────────────────────────┤
│         Logging Layer        ▼                                │
│  ┌───────────────────────────────────────────────┐           │
│  │              SLF4J MDC                        │           │
│  │  ┌─────────────────────────────────────┐     │           │
│  │  │  traceId:  04bf92f3577b34da...      │     │           │
│  │  │  spanId:   36bd32b7a5712a1a         │     │           │
│  │  │  parentId: 00f067aa0ba902b7         │     │           │
│  │  └─────────────────────────────────────┘     │           │
│  └───────────────────────────────────────────────┘           │
│                              │                                │
└──────────────────────────────┼────────────────────────────────┘
                               ▼
                    ┌────────────────────┐
                    │  Jaeger Collector  │
                    │  (Trace Storage)   │
                    └────────────────────┘

2.2 核心组件说明

2.2.1 CustomMDCScopeManager

职责：实现 OpenTracing 的 ScopeManager 接口，管理 Span 的激活与传播

关键实现：

private final ThreadLocal<CustomMDCScope> tlsScope = new ThreadLocal<>();

@Override
public Scope activate(Span span) {
    return new CustomMDCScope(span);
}

@Override
public Span activeSpan() {
    CustomMDCScope scope = tlsScope.get();
    return scope == null ? null : scope.wrapped;
}

设计要点：

使用 ThreadLocal 保证线程隔离
支持 Scope 的嵌套（通过链表结构维护 previous）
实现懒激活：仅在调用 activate() 时才注入 MDC

2.2.2 CustomMDCScope

职责：实现 OpenTracing 的 Scope 接口，管理单个 Span 的生命周期

核心机制：快照-注入-恢复（Snapshot-Inject-Restore）

CustomMDCScope(Span span) {
    // 1. 保存当前 MDC 快照
    this.previousTraceId = MDC.get("traceId");
    this.previousSpanId = MDC.get("spanId");
    
    // 2. 建立链表关系（支持嵌套）
    this.previous = CustomMDCScopeManager.this.tlsScope.get();
    CustomMDCScopeManager.this.tlsScope.set(this);
    
    // 3. 注入新的 trace 上下文
    MDC.put("traceId", span.context().toTraceId());
    MDC.put("spanId", span.context().toSpanId());
}

@Override
public void close() {
    // 4. 恢复到上一层 Scope
    CustomMDCScopeManager.this.tlsScope.set(previous);
    
    // 5. 恢复 MDC 到快照状态
    restoreMDC("traceId", previousTraceId);
    restoreMDC("spanId", previousSpanId);
}

3. 关键流程设计

3.1 接收远程 Trace 上下文的流程

┌─────────────┐
│ HTTP Request│
│  Headers    │
│ uber-trace-id: 4bf92f3577b...│
└──────┬──────┘
       │
       ▼
┌──────────────────────────────────┐
│ 1. 解析 HTTP Header              │
│    - 提取 traceId (128-bit)      │
│    - 提取 parentSpanId (64-bit)  │
│    - 提取 flags (采样标记)       │
└──────┬───────────────────────────┘
       │
       ▼
┌──────────────────────────────────┐
│ 2. 构造 JaegerSpanContext        │
│    long[] parts = splitTraceId() │
│    new JaegerSpanContext(        │
│      traceIdHigh,                │
│      traceIdLow,                 │
│      parentSpanId,               │
│      parentOfParentId,           │
│      flags                       │
│    )                             │
└──────┬───────────────────────────┘
       │
       ▼
┌──────────────────────────────────┐
│ 3. 创建子 Span                   │
│    tracer.buildSpan("child-span")│
│          .asChildOf(parentContext)│
│          .withTag(...)           │
│          .start()                │
└──────┬───────────────────────────┘
       │
       ▼
┌──────────────────────────────────┐
│ 4. 激活 Span 到当前线程          │
│    try (Scope scope =            │
│      tracer.scopeManager()       │
│            .activate(childSpan)) │
│    {                             │
│      // MDC 自动注入             │
│      // 业务逻辑执行             │
│    } // MDC 自动清理             │
└──────────────────────────────────┘

3.2 嵌套 Span 的 MDC 管理流程

时间线 ────────────────────────────────────────────>

ThreadLocal Stack:
┌─────────────────────────────────────────────────┐
│  null                                           │
└─────────────────────────────────────────────────┘

activate(spanA)
┌─────────────────────────────────────────────────┐
│  ScopeA: {traceId: xxx, spanId: A, previous: null}│
└─────────────────────────────────────────────────┘
MDC: {traceId: xxx, spanId: A}

  activate(spanB)  // 嵌套调用
  ┌─────────────────────────────────────────────────┐
  │  ScopeB: {traceId: xxx, spanId: B, previous: ScopeA}│
  └─────────────────────────────────────────────────┘
  MDC: {traceId: xxx, spanId: B}  // spanId 更新

    // 业务代码执行
    log.info("Processing...")  // 日志携带 spanId=B

  close(ScopeB)
  ┌─────────────────────────────────────────────────┐
  │  ScopeA: {traceId: xxx, spanId: A, previous: null}│
  └─────────────────────────────────────────────────┘
  MDC: {traceId: xxx, spanId: A}  // 恢复到 spanId=A

close(ScopeA)
┌─────────────────────────────────────────────────┐
│  null                                           │
└─────────────────────────────────────────────────┘
MDC: {}  // 完全清空

3.3 Trace ID 分割算法

Jaeger 支持 128-bit 的 traceId，但 Java long 仅为 64-bit，因此需要分割：

/**
 * 将十六进制 traceId 字符串分割为高64位和低64位
 * 
 * 示例:
 * 输入: "04bf92f3577b34da63ce929d0e0e4736" (32个十六进制字符 = 128 bit)
 * 输出: [0x04bf92f3577b34da, 0x63ce929d0e0e4736]
 */
public static long[] splitTraceId(String traceIdHex) {
    if (traceIdHex.length() <= 16) {
        // 仅有低64位，高位为0
        return new long[]{0L, parseLong(traceIdHex)};
    } else {
        // 分割为高64位和低64位
        String highHex = traceIdHex.substring(0, traceIdHex.length() - 16);
        String lowHex = traceIdHex.substring(traceIdHex.length() - 16);
        return new long[]{parseLong(highHex), parseLong(lowHex)};
    }
}

4. 配置与集成

4.1 Tracer 初始化配置

static Tracer tracer = new Configuration("order-service")
    .withSampler(
        new Configuration.SamplerConfiguration()
            .withType("const")
            .withParam(1)  // 采样率 100%
    )
    .withReporter(
        new Configuration.ReporterConfiguration()
            .withLogSpans(true)  // 开发环境启用日志输出
            .withSender(
                new Configuration.SenderConfiguration()
                    .withAgentHost("localhost")
                    .withAgentPort(6831)
            )
    )
    .getTracerBuilder()
    .withScopeManager(new CustomMDCScopeManager())  // 关键：注入自定义管理器
    .build();

4.2 Logback 配置

<configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} [traceId=%X{traceId} spanId=%X{spanId}] - %msg%n</pattern>
        </encoder>
    </appender>
    
    <appender name="JSON" class="ch.qos.logback.core.FileAppender">
        <file>logs/app.json</file>
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <includeMdcKeyName>traceId</includeMdcKeyName>
            <includeMdcKeyName>spanId</includeMdcKeyName>
            <includeMdcKeyName>parentId</includeMdcKeyName>
        </encoder>
    </appender>
    
    <root level="INFO">
        <appender-ref ref="CONSOLE" />
        <appender-ref ref="JSON" />
    </root>
</configuration>

4.3 Spring Boot 集成（可选）

@Configuration
public class TracingConfig {
    
    @Bean
    public Tracer jaegerTracer() {
        return new Configuration(
                env.getProperty("spring.application.name", "unknown-service")
            )
            .withSampler(samplerConfig())
            .withReporter(reporterConfig())
            .getTracerBuilder()
            .withScopeManager(new CustomMDCScopeManager())
            .build();
    }
    
    @Bean
    public TracingFilter tracingFilter(Tracer tracer) {
        return new TracingFilter(tracer);
    }
}

5. 使用场景与最佳实践

5.1 接收上游 Trace 上下文

@RestController
public class OrderController {
    
    @GetMapping("/order/{id}")
    public Order getOrder(
        @PathVariable String id,
        @RequestHeader(value = "uber-trace-id", required = false) String uberTraceId
    ) {
        JaegerSpanContext parentContext = parseUberTraceId(uberTraceId);
        
        Span span = tracer.buildSpan("get-order")
            .asChildOf(parentContext)  // 关键：链接远程父 Span
            .withTag(Tags.SPAN_KIND, Tags.SPAN_KIND_SERVER)
            .withTag("order.id", id)
            .start();
        
        try (Scope scope = tracer.scopeManager().activate(span)) {
            log.info("Processing order request");  // 自动携带 traceId/spanId
            return orderService.getById(id);
        } finally {
            span.finish();
        }
    }
}

5.2 向下游传递 Trace 上下文

public class PaymentClient {
    
    public void processPayment(String orderId) {
        Span span = tracer.buildSpan("call-payment-service")
            .withTag(Tags.SPAN_KIND, Tags.SPAN_KIND_CLIENT)
            .start();
        
        try (Scope scope = tracer.scopeManager().activate(span)) {
            HttpHeaders headers = new HttpHeaders();
            
            // 注入 trace 上下文到 HTTP Header
            tracer.inject(
                span.context(),
                Format.Builtin.HTTP_HEADERS,
                new HttpHeadersCarrier(headers)
            );
            
            restTemplate.exchange(
                "http://payment-service/pay",
                HttpMethod.POST,
                new HttpEntity<>(paymentRequest, headers),
                PaymentResponse.class
            );
        } finally {
            span.finish();
        }
    }
}

5.3 异步场景处理

@Service
public class AsyncOrderService {
    
    @Autowired
    private Tracer tracer;
    
    @Autowired
    private ExecutorService executorService;
    
    public void processOrderAsync(String orderId) {
        Span parentSpan = tracer.activeSpan();  // 获取当前 Span
        
        executorService.submit(() -> {
            // 在新线程中重新激活父 Span
            Span asyncSpan = tracer.buildSpan("async-process")
                .asChildOf(parentSpan)
                .start();
            
            try (Scope scope = tracer.scopeManager().activate(asyncSpan)) {
                log.info("Async processing order");  // MDC 正确注入
                // 业务逻辑
            } finally {
                asyncSpan.finish();
            }
        });
    }
}

6. 关键设计决策

6.1 为什么不直接在业务代码中操作 MDC？

问题：手动管理容易遗漏清理，导致线程池复用时 traceId 污染

解决方案：通过 ScopeManager 的生命周期管理，在 activate() 时注入，在 close() 时自动清理

6.2 为什么需要保存 MDC 快照？

场景：嵌套 Span 调用时，需要在子 Span 结束后恢复父 Span 的 MDC

实现：

// 进入子 Span 时
this.previousTraceId = MDC.get("traceId");  // 保存快照
MDC.put("traceId", childSpan.context().toTraceId());  // 覆盖

// 退出子 Span 时
restoreMDC("traceId", previousTraceId);  // 恢复快照

6.3 为什么使用 ThreadLocal 而不是 InheritableThreadLocal？

考量：

ThreadLocal：严格线程隔离，适合同步场景
InheritableThreadLocal：子线程继承父线程值，但在线程池复用时容易出现上下文泄漏

推荐：异步场景显式传递 Span，而非依赖自动继承

7. 监控与调试

7.1 日志输出示例

45:32.123 [http-nio-8080-exec-1] INFO  c.w.OrderService [traceId=04bf92f3577b34da63ce929d0e0e4736 spanId=36bd32b7a5712a1a] - Processing order ORD-001
45:32.234 [http-nio-8080-exec-1] INFO  c.w.PaymentClient [traceId=04bf92f3577b34da63ce929d0e0e4736 spanId=7f3a28b9c4d5e6a1] - Calling payment service
45:32.456 [http-nio-8080-exec-1] INFO  c.w.OrderService [traceId=04bf92f3577b34da63ce929d0e0e4736 spanId=36bd32b7a5712a1a] - Order processed successfully

7.2 Jaeger UI 查询

在 Jaeger UI 中可以：

通过 traceId 04bf92f3577b34da63ce929d0e0e4736 查看完整调用链
查看每个 Span 的 Tags（如 db.statement, http.status_code）
查看 Span 之间的父子关系和耗时分布

7.3 常见问题排查

问题现象	可能原因	排查方法
日志中 traceId 为空	未激活 Span 或 ScopeManager 未正确配置	检查 `activate()` 调用和 Tracer 构建
traceId 在不同请求间串台	MDC 未正确清理（线程池复用）	确保 `finally` 块中调用 `MDC.remove()`
子 Span 未链接到父 Span	`asChildOf()` 参数错误	验证 parentSpanId 是否正确解析
Jaeger 中看不到 Span	采样率设置为0或 Reporter 配置错误	检查 `withParam(1)` 和网络连通性

8. 性能考量

8.1 性能影响分析

操作	耗时	影响
MDC.put()	< 1μs	可忽略
ThreadLocal.get()	< 1μs	可忽略
Span.start()	~10μs	低
Span.finish() + 上报	~100μs	异步上报，对主流程影响小

8.2 优化建议

合理控制采样率：生产环境可设置为 0.1（10%）以降低存储成本
批量上报：Reporter 配置 withFlushInterval(1000) 批量发送 Span
避免过度 Span：不要为每个数据库查询都创建 Span，控制粒度

9. 扩展方向

9.1 支持响应式编程（Reactor/WebFlux）

public class ReactorScopeManager implements ScopeManager {
    @Override
    public Scope activate(Span span) {
        return new ReactorScope(span);
    }
    
    static class ReactorScope implements Scope {
        ReactorScope(Span span) {
            // 使用 Reactor Context 而非 ThreadLocal
            Context.of("span", span);
        }
    }
}

9.2 集成 Spring Cloud Sleuth

Spring Cloud Sleuth 提供了开箱即用的分布式追踪，可替代本方案：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>

9.3 支持 OpenTelemetry

OpenTelemetry 是新一代可观测性标准，建议未来迁移：

OpenTelemetry openTelemetry = AutoConfiguredOpenTelemetrySdk
    .initialize()
    .getOpenTelemetrySdk();

10. 总结

本方案通过自定义 ScopeManager 实现了 Jaeger Trace 与 SLF4J MDC 的无缝集成，具备以下特点：

✅ 自动化：Scope 生命周期管理，无需手动操作 MDC
✅ 线程安全：ThreadLocal 隔离 + 快照恢复机制
✅ 嵌套支持：链表结构维护多层 Span 关系
✅ 生产可用：已考虑线程池复用、异步场景等边界情况

该方案适用于需要精细控制 trace 上下文传播的微服务架构，特别是需要接收上游 trace 信息的服务网关、BFF 层等场景。

1. 方案概述​

1.1 背景与目标​

1.2 核心价值​

2. 架构设计​

2.1 整体架构图​

2.2 核心组件说明​

2.2.1 CustomMDCScopeManager​

2.2.2 CustomMDCScope​

3. 关键流程设计​

3.1 接收远程 Trace 上下文的流程​

3.2 嵌套 Span 的 MDC 管理流程​

3.3 Trace ID 分割算法​

4. 配置与集成​

4.1 Tracer 初始化配置​

4.2 Logback 配置​

4.3 Spring Boot 集成（可选）​

5. 使用场景与最佳实践​

5.1 接收上游 Trace 上下文​

5.2 向下游传递 Trace 上下文​

5.3 异步场景处理​

6. 关键设计决策​

6.1 为什么不直接在业务代码中操作 MDC？​

6.2 为什么需要保存 MDC 快照？​

6.3 为什么使用 ThreadLocal 而不是 InheritableThreadLocal？​

7. 监控与调试​

7.1 日志输出示例​

7.2 Jaeger UI 查询​

7.3 常见问题排查​

8. 性能考量​

8.1 性能影响分析​

8.2 优化建议​

9. 扩展方向​

9.1 支持响应式编程（Reactor/WebFlux）​

9.2 集成 Spring Cloud Sleuth​

9.3 支持 OpenTelemetry​

10. 总结​