3. OpenTelemetry SDK 初始化：全局 TracerProvider 配置、Exporter 与 Sampler 的选择

在分布式系统中，OpenTelemetry SDK 的初始化是接入可观测性的第一步，也是决定数据质量与系统开销的关键环节。本章聚焦于 SDK 初始化时的三大核心决策：全局 TracerProvider 的配置、Exporter（导出器）的选择与Sampler（采样器）的配置。错误的初始化配置可能导致数据丢失、性能下降或链路断裂，因此理解其原理与最佳实践至关重要。

3.1 全局 TracerProvider 配置

OpenTelemetry 采用 全局单例模式 管理 TracerProvider。所有组件（如中间件、业务代码）通过全局实例获取 Tracer，从而保证 Span 的创建与上下文传播一致。初始化流程通常包含以下步骤：

1. 创建 Resource（资源）：描述服务元数据，如服务名、版本、环境。
2. 配置 SpanProcessor（处理器）：决定 Span 的生命周期管理方式（同步/异步）。
3. 绑定 Exporter：将处理后的 Span 数据发送到后端。
4. 设置 Sampler：控制哪些 Span 被记录与导出。
5. 注册为全局：调用 setGlobalTracerProvider() 使配置生效。

以下是一个典型的 Java SDK 初始化代码示例：

// 1. 创建 Resource
Resource resource = Resource.getDefault()
    .merge(Resource.create(Attributes.of(
        ResourceAttributes.SERVICE_NAME, "order-service",
        ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "production"
    )));

// 2. 配置 SpanProcessor（使用 BatchSpanProcessor 异步导出）
SpanProcessor spanProcessor = BatchSpanProcessor.builder(otlpExporter).build();

// 3. 构建 TracerProvider
SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
    .setResource(resource)
    .addSpanProcessor(spanProcessor)
    .setSampler(Sampler.alwaysOn())
    .build();

// 4. 注册为全局
OpenTelemetrySdk.builder()
    .setTracerProvider(tracerProvider)
    .buildAndRegisterGlobal();

3.2 Exporter 的选择与配置

Exporter 负责将 Span 数据序列化并发送到后端存储或分析系统。根据传输协议与目标系统的不同，OpenTelemetry 提供了多种 Exporter 实现。下表对比了主流 Exporter 的适用场景与特性：

Exporter 的配置通常涉及端点地址、超时时间、重试策略与压缩方式。以下是一个 OTLP Exporter 的配置示例：

// OTLP gRPC Exporter 配置
OtlpGrpcSpanExporter exporter = OtlpGrpcSpanExporter.builder()
    .setEndpoint("http://otel-collector:4317")  // Collector 地址
    .setTimeout(10, TimeUnit.SECONDS)            // 超时时间
    .addHeader("api-key", "your-api-key")        // 认证头
    .setCompression("gzip")                      // 启用压缩
    .build();

3.3 Sampler 的选择与策略

采样器（Sampler）决定了哪些 Span 被记录并最终导出。在高吞吐系统中，全量采集会带来巨大的存储与网络开销，合理的采样策略能在数据完整性与成本之间取得平衡。OpenTelemetry 内置了以下采样器：

以下 SVG 图展示了采样决策在调用链中的传递过程：

3.4 初始化流程全景

将上述组件整合后，完整的 SDK 初始化流程如下图所示。该图展示了从 Resource 创建到全局注册的完整链路，以及 Exporter 与 Sampler 在其中的位置：

3.5 常见初始化错误与排查

在实际项目中，SDK 初始化阶段的错误往往隐蔽且难以排查。以下列出三种典型错误及其解决方案：