4. OpenTelemetry 与 Jaeger：OTel 协议、SDK 接入、Exporter 配置

在事故响应场景中，快速定位故障根因依赖于高质量、低延迟的链路数据。OpenTelemetry（OTel）已成为分布式追踪的事实标准，而 Jaeger 作为原生支持 OTel 的后端，二者结合构成了现代可观测性基础设施的核心。本节将深入剖析 OTel 协议、SDK 接入方式以及 Exporter 配置，帮助你在变更窗口内快速部署并获取有效追踪数据。

4.1 OTel 协议：数据模型与传输规范

OpenTelemetry 协议（OTLP）定义了链路、指标、日志的统一数据模型和传输格式。理解 OTLP 是正确配置 Jaeger 的基础。

4.2 OTel SDK 接入：从代码到链路

SDK 接入是生成有效追踪数据的起点。以下以 Java 为例，展示如何在微服务中集成 OTel SDK 并导出至 Jaeger。

4.2.1 依赖引入与自动配置

<!-- pom.xml -->
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>1.40.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
    <version>1.40.0</version>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
    <version>1.40.0</version>
</dependency>

4.2.2 手动创建 Span 示例

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;

public class OrderService {
    private final Tracer tracer;

    public OrderService(OpenTelemetry openTelemetry) {
        this.tracer = openTelemetry.getTracer("order-service");
    }

    public void processOrder(String orderId) {
        Span span = tracer.spanBuilder("processOrder")
                .setAttribute("order.id", orderId)
                .setAttribute("service.version", "1.2.3")
                .startSpan();
        try (Scope scope = span.makeCurrent()) {
            // 业务逻辑：数据库查询、外部调用等
            Thread.sleep(100); // 模拟耗时
            span.addEvent("order.processed", Attributes.of(
                    AttributeKey.stringKey("result"), "success"));
        } catch (Exception e) {
            span.recordException(e);
            span.setStatus(StatusCode.ERROR, "订单处理失败");
        } finally {
            span.end();
        }
    }
}

4.3 Exporter 配置：将数据送达 Jaeger

Exporter 负责将 SDK 采集的 Span 数据发送到 Jaeger 后端。配置错误是变更窗口内追踪数据丢失的首要原因。

4.3.1 环境变量配置（推荐生产使用）

# 设置 OTLP gRPC 导出器
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger-collector:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_SERVICE_NAME=order-service
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.version=1.2.3

# 采样配置（事故响应时建议全量采样）
OTEL_TRACES_SAMPLER=always_on

4.3.2 Java 代码级配置

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;

public class TelemetryConfig {
    public static OpenTelemetry initJaegerExporter() {
        OtlpGrpcSpanExporter exporter = OtlpGrpcSpanExporter.builder()
                .setEndpoint("http://jaeger-collector:4317")
                .setTimeout(10, java.util.concurrent.TimeUnit.SECONDS)
                .build();

        SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
                .addSpanProcessor(BatchSpanProcessor.builder(exporter)
                        .setMaxExportBatchSize(512)
                        .setExporterTimeout(30, java.util.concurrent.TimeUnit.SECONDS)
                        .build())
                .build();

        return OpenTelemetrySdk.builder()
                .setTracerProvider(tracerProvider)
                .build();
    }
}

4.4 架构总览：从 SDK 到 Jaeger 的完整链路

下图展示了 OTel SDK 采集、Exporter 传输、Jaeger 后端存储与查询的完整数据流。

4.5 配置清单：变更窗口快速验证

在事故响应变更窗口内，使用以下清单快速验证 OTel 到 Jaeger 的连通性：

1. 检查 Exporter 端点：确认 OTEL_EXPORTER_OTLP_ENDPOINT 指向正确的 Jaeger Collector 地址和端口（默认 4317）。
2. 验证协议一致性：SDK 端使用 gRPC 时，Jaeger Collector 必须启用 gRPC 接收器（--collector.otlp.enabled=true）。
3. 确认采样策略：事故定位期间设置 OTEL_TRACES_SAMPLER=always_on，避免因采样丢失关键链路。
4. 检查网络连通性：使用 telnet jaeger-collector 4317 或 grpcurl 测试端口可达性。
5. 查看 SDK 日志：启用 OTel SDK 的调试日志（OTEL_LOG_LEVEL=debug），确认无导出错误。
6. Jaeger UI 验证：在 Jaeger UI 中搜索服务名，确认有新的 Trace 数据到达。

4.6 常见问题与排查

通过掌握 OTel 协议、SDK 接入和 Exporter 配置，你可以在事故响应变更窗口内快速建立可靠的分布式追踪管道，为后续的根因定位提供坚实的数据基础。