4、应用接入Jaeger（Java）：使用OpenTelemetry Java Agent自动埋点、配置导出端点与采样策略

Java 应用接入 Jaeger 最简洁的方式是使用 OpenTelemetry Java Agent。该 Agent 通过字节码增强技术自动拦截主流框架（如 Spring Boot、gRPC、Servlet、JDBC、HTTP Client 等）的调用，无需修改业务代码即可生成分布式追踪数据。本章将详细讲解 Agent 的安装、配置导出端点以及采样策略的设定。

4.1 OpenTelemetry Java Agent 自动埋点原理

Agent 在 JVM 启动时通过 javaagent 参数挂载，利用 Instrumentation API 修改目标类的字节码，在方法入口/出口插入 Span 创建与结束逻辑。整个过程对应用代码完全透明。

4.2 快速接入步骤

4.2.1 下载 Agent JAR

从 OpenTelemetry Java Instrumentation 官方 Releases 页面下载最新版本的 opentelemetry-javaagent.jar。建议固定版本号用于生产环境，避免自动升级引入不兼容变更。

4.2.2 配置 JVM 启动参数

在应用启动命令中添加以下参数，即可完成基础接入：

java -javaagent:/path/to/opentelemetry-javaagent.jar \
     -Dotel.service.name=order-service \
     -Dotel.traces.exporter=otlp \
     -Dotel.exporter.otlp.endpoint=http://jaeger-collector:4318 \
     -jar myapp.jar

4.3 配置导出端点

导出端点决定了 Span 数据发送的目标地址。除 JVM 参数外，也支持通过环境变量或 YAML 配置文件设定。以下为三种配置方式对比：

环境变量示例：

export OTEL_SERVICE_NAME=payment-service
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger-collector:4318

Agent 配置文件示例（otel-config.yaml）：

otel:
  service:
    name: inventory-service
  traces:
    exporter: otlp
  exporter:
    otlp:
      endpoint: http://jaeger-collector:4318
      headers:
        - "Authorization=Bearer mytoken"

使用配置文件时，启动参数需指定：-Dotel.javaagent.configuration-file=/path/to/otel-config.yaml。

4.4 采样策略配置

采样策略控制哪些请求被记录为 Trace，直接影响存储成本和性能开销。OpenTelemetry Java Agent 支持多种采样器，通过 -Dotel.traces.sampler 参数指定。

4.4.1 常用采样器对比

4.4.2 生产环境推荐配置

生产环境建议使用 parentbased_traceidratio 采样器，并设置合理的采样比率：

# 采样 10% 的请求，并继承上游采样决策
-Dotel.traces.sampler=parentbased_traceidratio
-Dotel.traces.sampler.arg=0.1

4.4.3 基于头部属性的自定义采样

若需要根据 HTTP 头部（如 X-Debug）或请求参数动态采样，可通过自定义 Sampler 实现。以下为 Spring Boot 中注册自定义采样器的示例：

import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.context.Context;
import io.opentelemetry.sdk.trace.data.LinkData;
import io.opentelemetry.sdk.trace.samplers.Sampler;
import io.opentelemetry.sdk.trace.samplers.SamplingResult;
import java.util.List;

public class DebugHeaderSampler implements Sampler {
    private final Sampler fallback;

    public DebugHeaderSampler(Sampler fallback) {
        this.fallback = fallback;
    }

    @Override
    public SamplingResult shouldSample(Context parentContext, String traceId,
                                       String name, SpanKind spanKind,
                                       Attributes attributes, List<LinkData> parentLinks) {
        // 从 Context 中提取 HTTP 头部（需配合手动拦截器）
        String debugFlag = (String) parentContext.get("X-Debug");
        if ("true".equalsIgnoreCase(debugFlag)) {
            return SamplingResult.recordAndSample(); // 强制采样
        }
        return fallback.shouldSample(parentContext, traceId, name, spanKind, attributes, parentLinks);
    }

    @Override
    public String getDescription() {
        return "DebugHeaderSampler{fallback=" + fallback.getDescription() + "}";
    }
}

在配置类中注册：

@Bean
public Sampler customSampler() {
    Sampler fallback = Sampler.parentBased(Sampler.traceIdRatioBased(0.1));
    return new DebugHeaderSampler(fallback);
}

4.5 验证接入是否成功

启动应用后，执行以下检查步骤：

1. 查看应用日志： 搜索 OTel SDK initialized 或 OpenTelemetry Java Agent initialized 确认 Agent 加载成功。
2. 触发请求： 访问应用的任意 HTTP 端点，或执行一次业务操作。
3. 检查 Jaeger UI： 打开 Jaeger 查询界面，在 Service 下拉框中应能看到配置的 otel.service.name。搜索最近时间段的 Trace，确认有数据展示。
4. 检查 Collector 日志： 若数据未到达，查看 Jaeger Collector 日志是否有连接拒绝或协议不匹配错误。

4.6 常见问题与避坑