4. OpenTelemetry SDK 集成：安装 OTel SDK、配置 Exporter、初始化 TracerProvider 与 MeterProvider

在异步任务编排系统中引入可观测性，核心步骤是将 OpenTelemetry SDK 嵌入到应用运行时。本章聚焦于 SDK 的安装、导出器（Exporter）配置以及 TracerProvider 与 MeterProvider 的初始化，为后续的链路追踪与指标采集奠定基础。

4.1 SDK 安装与版本选择

OpenTelemetry 提供多语言 SDK，以下以 Java 和 Python 为例说明安装方式。选择 SDK 时需注意与 Collector 及后端系统的版本兼容性。

// Maven
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
  <version>1.32.0</version>
</dependency>

pip install opentelemetry-api \
            opentelemetry-sdk \
            opentelemetry-exporter-otlp-proto-grpc

4.2 Exporter 配置：将数据发送到 Collector

Exporter 负责将 Span 和 Metric 数据序列化为 OTLP 格式，并通过 gRPC 或 HTTP 协议发送到 Collector。以下为 OTLP gRPC Exporter 的典型配置参数。

Java 代码示例： 通过环境变量或编程方式配置 Exporter。

// 方式一：环境变量（推荐用于容器化部署）
// OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
// OTEL_EXPORTER_OTLP_HEADERS=api-key=my-secret-key

// 方式二：编程配置
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;

OtlpGrpcSpanExporter spanExporter = OtlpGrpcSpanExporter.builder()
    .setEndpoint("http://otel-collector:4317")
    .addHeader("api-key", "my-secret-key")
    .setTimeout(10, java.util.concurrent.TimeUnit.SECONDS)
    .build();

4.3 初始化 TracerProvider 与 MeterProvider

TracerProvider 管理链路追踪的生命周期，MeterProvider 管理指标采集。两者均需在应用启动时完成初始化，并绑定 Exporter。

Java 完整初始化示例：

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.metrics.SdkMeterProvider;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter;
import io.opentelemetry.sdk.resources.Resource;

// 1. 创建 Exporter
OtlpGrpcSpanExporter spanExporter = OtlpGrpcSpanExporter.builder()
    .setEndpoint("http://otel-collector:4317").build();
OtlpGrpcMetricExporter metricExporter = OtlpGrpcMetricExporter.builder()
    .setEndpoint("http://otel-collector:4317").build();

// 2. 构建 TracerProvider
SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
    .addSpanProcessor(SimpleSpanProcessor.create(spanExporter))
    .setResource(Resource.getDefault()
        .toBuilder().put("service.name", "async-task-orchestrator").build())
    .build();

// 3. 构建 MeterProvider
SdkMeterProvider meterProvider = SdkMeterProvider.builder()
    .registerMetricReader(PeriodicMetricReader.builder(metricExporter)
        .setInterval(15, java.util.concurrent.TimeUnit.SECONDS).build())
    .setResource(Resource.getDefault()
        .toBuilder().put("service.name", "async-task-orchestrator").build())
    .build();

// 4. 组装 OpenTelemetry 实例
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(tracerProvider)
    .setMeterProvider(meterProvider)
    .build();

// 5. 获取 Tracer 和 Meter 实例
Tracer tracer = openTelemetry.getTracer("async-task-orchestrator");
Meter meter = openTelemetry.getMeter("async-task-orchestrator");

4.4 初始化流程架构图

下图展示了 SDK 初始化过程中各组件的关系与数据流向。

4.5 异步任务场景下的初始化注意事项

在异步任务编排系统中，SDK 初始化需要额外关注线程安全与上下文传播。以下为关键实践。

• 线程安全： TracerProvider 和 MeterProvider 是线程安全的，可在多个协程或线程中共享同一个实例。
• 上下文传播： 使用 Context.current() 在异步任务间传递 Span 上下文，避免链路断裂。
• 资源标签： 在 Resource 中添加 task.queue、task.type 等自定义属性，便于在 Collector 端进行数据过滤。
• 优雅关闭： 在应用关闭时调用 tracerProvider.shutdown() 和 meterProvider.shutdown()，确保未导出的数据被刷新。

4.6 初始化验证：快速检查清单

完成 SDK 集成后，使用以下清单验证配置是否正确。

通过以上步骤，异步任务编排系统已具备基础的链路追踪与指标采集能力。下一阶段将深入 Span 的创建与上下文传播，以覆盖复杂的异步调用链。