非Spring Boot遗留项目Brave分布式追踪配置及日志埋点求助

一、Brave 手动配置完整步骤（解决日志无Trace/Span ID问题） #

你之前的配置大概率遗漏了日志上下文绑定的关键步骤，以下是可落地的完整流程：

1. 引入必要依赖 #

确保Maven/Gradle中包含Brave核心、对应组件的instrumentation模块及Log4j2上下文集成包（版本保持一致）：

<!-- Maven 依赖示例 -->
<dependencies>
    <dependency>
        <groupId>io.zipkin.brave</groupId>
        <artifactId>brave</artifactId>
        <version>5.13.7</version> <!-- 替换为最新稳定版 -->
    </dependency>
    <!-- Jetty 服务端追踪 -->
    <dependency>
        <groupId>io.zipkin.brave</groupId>
        <artifactId>brave-instrumentation-jetty-server</artifactId>
        <version>5.13.7</version>
    </dependency>
    <!-- Apache HttpClient 追踪 -->
    <dependency>
        <groupId>io.zipkin.brave</groupId>
        <artifactId>brave-instrumentation-httpclient</artifactId>
        <version>5.13.7</version>
    </dependency>
    <!-- Log4j2 上下文绑定 -->
    <dependency>
        <groupId>io.zipkin.brave</groupId>
        <artifactId>brave-context-log4j2</artifactId>
        <version>5.13.7</version>
    </dependency>
    <!-- 可选：Zipkin上报器，如需将追踪数据发送到Zipkin服务 -->
    <dependency>
        <groupId>io.zipkin.reporter2</groupId>
        <artifactId>zipkin-reporter-brave</artifactId>
        <version>2.16.3</version>
    </dependency>
</dependencies>

2. 初始化Brave追踪器 #

创建全局配置类，绑定Log4j2上下文并配置Jetty、HttpClient的拦截逻辑：

import brave.Tracing;
import brave.http.HttpTracing;
import brave.instrumentation.jetty.server.TraceHandler;
import brave.instrumentation.httpclient.TracingHttpClientBuilder;
import brave.propagation.CurrentTraceContext;
import brave.propagation.ThreadLocalCurrentTraceContext;
import brave.context.log4j2.Log4j2ScopeDecorator;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.handler.HandlerList;
import org.apache.http.impl.client.CloseableHttpClient;

public class TracingInitializer {
    private static final String SERVICE_NAME = "your-service-id";

    // 全局Tracing实例
    private static Tracing tracing;

    static {
        // 关键：绑定Trace/Span ID到Log4j2上下文
        CurrentTraceContext currentTraceContext = ThreadLocalCurrentTraceContext.newBuilder()
                .addScopeDecorator(Log4j2ScopeDecorator.create())
                .build();

        tracing = Tracing.newBuilder()
                .localServiceName(SERVICE_NAME)
                .currentTraceContext(currentTraceContext)
                // 可选：配置Zipkin上报地址
                // .spanReporter(AsyncZipkinSpanReporter.create("http://zipkin-server:9411/api/v2/spans"))
                .build();
    }

    // 为Jetty添加追踪Handler
    public static void setupJettyTracing(Server server) {
        HttpTracing httpTracing = HttpTracing.create(tracing);
        TraceHandler traceHandler = new TraceHandler(httpTracing, server.getHandler());
        HandlerList handlerList = new HandlerList();
        handlerList.addHandler(traceHandler);
        server.setHandler(handlerList);
    }

    // 创建带追踪能力的Apache HttpClient
    public static CloseableHttpClient createTracedHttpClient() {
        HttpTracing httpTracing = HttpTracing.create(tracing);
        return TracingHttpClientBuilder.create(httpTracing).build();
    }
}

3. 修改Log4j2配置 #

在log4j2.xml或log4j2.properties中，将Trace ID和Span ID加入日志格式：

<!-- Log4j2 XML配置示例 -->
<Appenders>
    <Console name="Console" target="SYSTEM_OUT">
        <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - traceId=%X{traceId}, spanId=%X{spanId} - %msg%n"/>
    </Console>
</Appenders>

4. 启动时初始化 #

• Jetty启动前调用TracingInitializer.setupJettyTracing(server);
• 项目中所有Apache HttpClient实例，替换为TracingInitializer.createTracedHttpClient()创建的实例

二、无代码侵入的自动Instrumentation方案 #

如果不想修改业务代码，推荐使用Java Agent实现全链路自动追踪：

1. Brave Java Agent #

下载Brave Agent jar包，启动项目时添加JVM参数：

-javaagent:/path/to/brave-agent-5.13.7.jar
-Dbrave.service.name=your-service-id
-Dbrave.context.log4j2=true

Agent会自动拦截Jetty请求、Apache HttpClient调用，并将Trace/Span ID注入Log4j2上下文，无需修改任何业务代码。

2. OpenTelemetry Java Agent #

另一个无侵入方案，支持更多组件，启动时添加JVM参数：

-javaagent:/path/to/opentelemetry-javaagent-1.28.0.jar
-Dotel.service.name=your-service-id
-Dotel.traces.exporter=zipkin # 可选，如需上报到Zipkin

同时修改Log4j2的日志格式，替换为OpenTelemetry的变量：

<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - traceId=%X{trace_id}, spanId=%X{span_id} - %msg%n"/>

三、常见问题排查 #

• 日志无Trace ID：检查是否添加了Log4j2ScopeDecorator（手动配置）或启用了brave.context.log4j2=true（Agent方式）
• Jetty追踪不生效：确保TraceHandler在所有业务Handler之前执行
• HttpClient无追踪：确认使用了带追踪的实例，或Agent已正确加载

内容的提问来源于stack exchange，提问作者Sys32