Trace Plugin

对应模块: io.gitee.lcgyl:lcgyl-trace-plugin

全链路追踪监控插件，基于 OpenTracing 标准，实现分布式系统调用链的可视化追踪。

✨ 特性

• ✅ 自动埋点 - 自动拦截 Web MVC, RPC, DB, Cache 等关键路径
• ✅ 跨进程追踪 - 支持 HTTP/RPC 头部透传 Trace Context
• ✅ 日志关联 - 自动注入 Logback/Log4j2 MDC，实现 Logs 与 Trace 关联
• ✅ 采样策略 - 支持概率采样、自适应采样等多种策略
• ✅ LogContext 同步 - 自动同步 TraceId/SpanId 到 LogContext v2.2.0
• ✅ 结构化追踪日志 - TraceStructuredLogger 结构化输出 v2.2.0

🚀 快速开始

依赖引入

implementation 'io.gitee.lcgyl:lcgyl-trace-plugin:2.2.0'

配置

lcgyl:
  trace:
    enabled: true
    service-name: my-service
    sampling:
      rate: 1.0  # 采样率 0.0-1.0
    propagation:
      type: W3C  # W3C, B3, JAEGER
    exporter:
      type: otlp
      endpoint: http://localhost:4317

声明式追踪

@Service
public class OrderService {
    
    // 自动创建 Span，方法名作为 Span 名称
    @Trace
    public Order createOrder(OrderRequest request) {
        return orderRepository.save(new Order(request));
    }
    
    // 自定义 Span 名称和标签
    @Trace(name = "process-payment", tags = {"type=payment"})
    public PaymentResult processPayment(String orderId, BigDecimal amount) {
        return paymentGateway.charge(orderId, amount);
    }
}

v2.2.0 新功能：LogContext 同步

@Service
public class BusinessService {
    
    @Autowired
    private LogContextTraceSync traceSync;
    
    public void process() {
        // 自动将 TraceId/SpanId 同步到 LogContext（MDC）
        try (var scope = traceSync.syncToLogContext()) {
            log.info("处理业务");  // 日志自动携带 traceId、spanId
            doBusinessLogic();
        }
    }
}

v2.2.0 新功能：结构化追踪日志

@Service
public class ApiHandler {
    
    @Autowired
    private TraceStructuredLogger traceLogger;
    
    public void handleRequest(Request request) {
        traceLogger.info("request.received")
            .field("path", request.getPath())
            .field("method", request.getMethod())
            .field("clientIp", request.getClientIp())
            .log();
        // 输出: {"event":"request.received","path":"/api/orders","method":"POST","traceId":"abc123","spanId":"def456"}
        
        // 处理完成后记录
        traceLogger.info("request.completed")
            .field("statusCode", 200)
            .field("durationMs", 45)
            .log();
    }
}

跨服务追踪

@Service
public class RemoteService {
    
    @Inject
    private HttpClient httpClient;
    
    @Inject
    private TraceContextPropagator propagator;
    
    public String callRemote(String url) {
        // Trace Context 自动通过 HTTP Header 传递到下游服务
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .build();
        
        // 框架自动注入 traceparent, tracestate 等头部
        return httpClient.send(request).body();
    }
}