📚 课程目录第4章 OpenTelemetry SDK配置

4. OpenTelemetry SDK 配置：Python SDK 安装、Provider 配置、Exporter 选择

本章聚焦于 OpenTelemetry Python SDK 的落地配置，涵盖 SDK 安装、Provider 初始化以及 Exporter 的选型与对比。正确的 SDK 配置是后续指标采集与任务调度的基础，直接影响数据链路的可靠性、性能与可维护性。

4.1 Python SDK 安装与环境准备

OpenTelemetry Python 生态采用模块化设计，核心 SDK 与 API 分离，指标、日志、追踪各自独立。安装时需根据采集目标选择对应的 Instrumentation 包。

核心安装命令：

# 安装核心 SDK 与 API
pip install opentelemetry-api
pip install opentelemetry-sdk

# 安装指标相关模块
pip install opentelemetry-metrics

# 安装 OTLP Exporter（gRPC 与 HTTP 二选一或同时安装）
pip install opentelemetry-exporter-otlp-proto-grpc
pip install opentelemetry-exporter-otlp-proto-http

# 安装常用 Instrumentation（以数据库与系统指标为例）
pip install opentelemetry-instrumentation-system-metrics
pip install opentelemetry-instrumentation-mysql
pip install opentelemetry-instrumentation-psycopg2

版本对齐提示： 建议使用 opentelemetry-sdk ≥ 1.20.0，确保 MetricReader 与 PeriodicExportingMetricReader 接口稳定。生产环境应锁定版本号，避免自动升级引入不兼容变更。

4.2 Provider 配置：从 MeterProvider 到 MetricReader

指标采集的核心链路为：MeterProvider → Meter → Instrument → MetricReader → Exporter。Provider 是全局入口，负责管理 Meter 实例与导出行为。

4.2.1 标准配置流程

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import (
    PeriodicExportingMetricReader,
    ConsoleMetricExporter,
)
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
    OTLPMetricExporter,
)

# 1. 创建 Exporter（以 OTLP gRPC 为例）
otlp_exporter = OTLPMetricExporter(
    endpoint="http://otel-collector:4317",
    insecure=True,  # 生产环境建议使用 TLS
)

# 2. 创建 MetricReader，设置导出间隔（默认 60s）
reader = PeriodicExportingMetricReader(
    exporter=otlp_exporter,
    export_interval_millis=30_000,  # 30 秒导出一次
    export_timeout_millis=10_000,   # 导出超时 10 秒
)

# 3. 创建 MeterProvider 并设置为全局默认
provider = MeterProvider(metric_readers=[reader])
metrics.set_meter_provider(provider)

# 4. 获取 Meter 实例，开始创建指标
meter = metrics.get_meter("db-migration-meter", version="1.0.0")

4.2.2 多 Reader 与多 Exporter 场景

在数据库迁移任务中，常需要同时将指标输出到控制台（调试）和 OTLP Collector（生产）。可通过传入多个 MetricReader 实现。

console_reader = PeriodicExportingMetricReader(
    exporter=ConsoleMetricExporter(),
    export_interval_millis=60_000,
)

otlp_reader = PeriodicExportingMetricReader(
    exporter=OTLPMetricExporter(endpoint="http://collector:4317"),
    export_interval_millis=30_000,
)

provider = MeterProvider(metric_readers=[console_reader, otlp_reader])
metrics.set_meter_provider(provider)

性能注意： 多 Reader 会增加内存与 CPU 开销。生产环境建议仅保留一个 OTLP Exporter，Console Exporter 仅在开发或灰度阶段开启。

4.3 Exporter 选择：OTLP/gRPC vs HTTP 对比

OpenTelemetry 官方推荐使用 OTLP 协议进行数据导出。OTLP 支持 gRPC 和 HTTP/Protobuf 两种传输方式，两者在性能、兼容性与部署复杂度上存在差异。

对比维度	OTLP/gRPC	OTLP/HTTP
传输协议	HTTP/2 + Protobuf	HTTP/1.1 或 HTTP/2 + Protobuf
性能	高（流式传输、低延迟）	中等（请求-响应模式）
负载压缩	默认支持 gzip	需手动配置
防火墙友好	较差（需开放 4317 端口）	较好（标准 80/443 端口）
负载均衡	需 gRPC 感知的 LB	标准 HTTP LB 即可
SDK 依赖	需安装 grpcio	仅需 requests/httpx
推荐场景	内部网络、高性能采集	跨网络、边缘节点、受限环境

选型建议： 在数据库迁移任务调度场景中，若 Collector 与 SDK 部署在同一 Kubernetes 集群或内网，优先选择 OTLP/gRPC 以获得更低延迟与更高吞吐。若 SDK 运行在公网边缘节点或需要通过反向代理，选择 OTLP/HTTP 更稳定。

4.4 Exporter 配置示例：OTLP/gRPC 与 OTLP/HTTP

4.4.1 OTLP/gRPC Exporter 配置

from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter

exporter = OTLPMetricExporter(
    endpoint="http://otel-collector:4317",
    insecure=True,
    timeout=10,
    headers={
        "x-tenant-id": "migration-prod",
    },
)

4.4.2 OTLP/HTTP Exporter 配置

from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter

exporter = OTLPMetricExporter(
    endpoint="http://otel-collector:4318/v1/metrics",
    timeout=10,
    headers={
        "Authorization": "Bearer your-token",
    },
)

  关键参数说明：
  endpoint：Collector 地址，gRPC 默认端口 4317，HTTP 默认端口 4318。
insecure：是否启用 TLS。生产环境应设为 False 并配置证书。
headers：用于传递认证 Token、租户 ID 等元数据。
timeout：导出超时，建议根据网络状况调整，默认 10s。

4.5 SDK 配置架构总览

下图展示了 Python SDK 从指标创建到导出的完整链路，以及 Provider、Reader、Exporter 之间的协作关系。

4.6 常见配置陷阱与避坑指南

MeterProvider 未设置全局： 未调用 metrics.set_meter_provider(provider) 会导致 SDK 使用默认的 NoopMeterProvider，所有指标静默丢弃。
导出间隔过短： 设置 export_interval_millis 低于 10s 可能造成 Collector 压力过大，建议生产环境不低于 30s。
gRPC 连接未复用： 每次创建 Exporter 实例会新建 gRPC 通道，应复用 Exporter 对象，避免连接泄漏。
HTTP Exporter 缺少 Content-Type： OTLP/HTTP 要求请求头 Content-Type: application/x-protobuf，SDK 默认已处理，但自定义代理时需注意。
忽略资源属性： 未设置 Resource 会导致指标无法区分服务实例，建议在 Provider 初始化时注入 service.name、service.version、deployment.environment。

生产环境必做： 在 Provider 初始化时显式设置 Resource，并开启 TLS 加密。以下为完整生产级配置模板：

from opentelemetry.sdk.resources import Resource

resource = Resource.create({
    "service.name": "db-migration-scheduler",
    "service.version": "2.1.0",
    "deployment.environment": "production",
    "host.name": socket.gethostname(),
})

provider = MeterProvider(
    metric_readers=[reader],
    resource=resource,
)
metrics.set_meter_provider(provider)

4.7 多 Exporter 分流架构

在数据库迁移任务中，常需要将高精度指标（如迁移速率、延迟）发送到实时监控系统，同时将聚合指标发送到长期存储。下图展示了多 Exporter 分流架构。

4.8 本章小结

Python SDK 安装需按模块拆分，核心为 opentelemetry-sdk 与 opentelemetry-exporter-otlp-proto-*。
Provider 配置需依次创建 Exporter → MetricReader → MeterProvider，并设置全局实例。
OTLP/gRPC 适合内网高性能场景，OTLP/HTTP 适合跨网络与受限环境。
多 Exporter 分流可实现实时监控与长期归档并存，需注意导出间隔与资源开销的平衡。
Resource 属性、TLS 加密、Exporter 复用是生产环境不可忽视的配置项。