Trace监控与ErrorHandler报警联动的调试实践 - 第3节

3.1 OpenTelemetry 架构总览

OpenTelemetry（OTel）是 CNCF 孵化的可观测性标准，统一了 Trace、Metrics、Logs 三类信号的采集与导出。其核心架构分为四个层次：API、SDK、Exporter 和 Collector。理解这一分层是后续配置与调优的基础。

3.2 SDK 安装与初始化

SDK 是 OTel 的运行时核心，负责创建 Span、管理上下文、执行采样和导出。以下以 Python 和 Go 为例展示安装与基本初始化。

3.2.1 Python SDK 安装

pip install opentelemetry-api \
            opentelemetry-sdk \
            opentelemetry-exporter-otlp-proto-grpc \
            opentelemetry-instrumentation-flask \
            opentelemetry-instrumentation-requests

3.2.2 Go SDK 安装

go get go.opentelemetry.io/otel \
       go.opentelemetry.io/otel/sdk \
       go.opentelemetry.io/otel/exporters/otlp/otlptrace \
       go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc

3.2.3 初始化 TracerProvider（Python 示例）

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

# 1. 创建 Exporter
exporter = OTLPSpanExporter(endpoint="http://localhost:4317", insecure=True)

# 2. 创建 SpanProcessor（批量导出）
processor = BatchSpanProcessor(exporter)

# 3. 创建 TracerProvider 并注册 Processor
provider = TracerProvider()
provider.add_span_processor(processor)

# 4. 设置为全局 TraceProvider
trace.set_tracer_provider(provider)

# 5. 获取 Tracer 开始埋点
tracer = trace.get_tracer(__name__)

3.3 Exporter 配置详解

Exporter 负责将 Span 数据序列化并发送到后端。OTel 原生支持多种 Exporter，最常用的是 OTLP（OpenTelemetry Protocol）。

3.3.1 OTLP Exporter 配置示例（Go）

import (
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
)

func newExporter(ctx context.Context) (*otlptrace.Exporter, error) {
    // 创建 gRPC 连接选项
    opts := []otlptracegrpc.Option{
        otlptracegrpc.WithEndpoint("localhost:4317"),
        otlptracegrpc.WithInsecure(),
    }
    // 创建 Exporter
    exporter, err := otlptracegrpc.New(ctx, opts...)
    if err != nil {
        return nil, err
    }
    return exporter, nil
}

3.4 采样策略（Sampling）

采样是控制 Trace 数据量的关键手段。OTel SDK 内置多种采样器，可在不丢失关键链路的前提下大幅降低存储成本。

3.4.1 采样器类型对比

3.4.2 配置 TraceIdRatioBased 采样（Python）

from opentelemetry.sdk.trace.sampling import TraceIdRatioBased

# 10% 采样率
sampler = TraceIdRatioBased(rate=0.1)

provider = TracerProvider(sampler=sampler)
trace.set_tracer_provider(provider)

3.4.3 配置 ParentBased + 比例采样（Go）

import (
    "go.opentelemetry.io/otel/sdk/trace"
    "go.opentelemetry.io/otel/sdk/trace/sampling"
)

func newProvider() (*trace.TracerProvider, error) {
    // 父 Span 决定采样，根 Span 按 20% 采样
    sampler := sampling.ParentBased(
        sampling.TraceIDRatioBased(0.2),
    )
    provider := trace.NewTracerProvider(
        trace.WithSampler(sampler),
        // ... 其他配置
    )
    return provider, nil
}

3.5 本章小结

• OTel 架构：API → SDK → Exporter → Collector，层次清晰，可插拔。
• SDK 安装：Python 和 Go 均提供官方包，注意版本兼容性。
• Exporter 配置：OTLP 是首选协议，支持 gRPC 和 HTTP；生产环境必须配置 TLS 和超时。
• 采样策略：推荐 ParentBased(TraceIdRatioBased) 组合，兼顾链路完整性与成本控制。