📚 课程目录第4章 Python SDK环境搭建

4. Python SDK 环境搭建：安装与配置

本章将指导你在 Python 环境中完成 OpenTelemetry SDK 的安装与基础配置。这是构建链路追踪与告警聚合能力的第一步，确保你的值班机器人能够正确产生并导出遥测数据。

4.1 核心依赖包说明

OpenTelemetry Python 生态采用分层设计，我们只需安装三个核心包即可覆盖 90% 的链路追踪场景。下表列出了每个包的职责与版本约束：

包名	职责	最低版本建议	安装命令
`opentelemetry-api`	提供 Tracer、Span、Context 等核心接口与抽象层	>=1.20.0	`pip install opentelemetry-api`
`opentelemetry-sdk`	实现 API 接口，包含 SpanProcessor、Sampler、Exporter 等运行时组件	>=1.20.0	`pip install opentelemetry-sdk`
`opentelemetry-exporter-otlp-proto-grpc`	通过 gRPC 协议将遥测数据以 Protobuf 格式导出到 Collector 或后端	>=1.20.0	`pip install opentelemetry-exporter-otlp-proto-grpc`

版本对齐提示：三个包的主版本号必须保持一致，否则可能出现接口不兼容。建议使用

pip install "opentelemetry-api>=1.20,<2.0" "opentelemetry-sdk>=1.20,<2.0" "opentelemetry-exporter-otlp-proto-grpc>=1.20,<2.0"

锁定大版本。

4.2 安装步骤

推荐在虚拟环境中执行安装，避免污染全局 Python 环境。以下是标准安装流程：

创建并激活虚拟环境

python3 -m venv otel-env
source otel-env/bin/activate   # Linux/macOS
# 或 otel-env\Scripts\activate  # Windows

安装核心包

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

验证安装

pip list | grep opentelemetry

预期输出应包含以下三个包且版本一致：

opentelemetry-api              1.22.0
opentelemetry-sdk              1.22.0
opentelemetry-exporter-otlp-proto-grpc 1.22.0

常见安装失败原因：

gRPC 依赖编译失败：在 macOS 上需先安装 grpcio 二进制轮子，执行 pip install grpcio。
Python 版本过低：OpenTelemetry Python SDK 要求 Python 3.8+，请使用 python3 --version 确认。
网络代理问题：使用 pip install --proxy=http://your-proxy:port 指定代理。

4.3 环境变量配置

OpenTelemetry Python SDK 通过环境变量实现零代码配置。你无需在代码中硬编码端点、服务名等参数，只需设置以下变量即可让 SDK 自动读取：

环境变量	必填	说明	示例值
`OTEL_SERVICE_NAME`	是	标识当前服务的名称，在链路中作为服务节点名	`robot-alert-service`
`OTEL_EXPORTER_OTLP_ENDPOINT`	是	OTLP gRPC 接收端地址，通常是 OpenTelemetry Collector 的地址	`http://otel-collector:4317`
`OTEL_EXPORTER_OTLP_PROTOCOL`	否	导出协议，默认 `grpc`，也可设为 `http/protobuf`	`grpc`
`OTEL_TRACES_SAMPLER`	否	采样策略，默认 `parentbased_always_on`	`parentbased_always_on`
`OTEL_TRACES_SAMPLER_ARG`	否	采样参数，与采样策略配合使用	`0.1`（概率采样时使用）
`OTEL_RESOURCE_ATTRIBUTES`	否	附加资源属性，多个属性用逗号分隔	`deployment.environment=production,version=1.0`

在启动 Python 应用前，通过 export 或 .env 文件设置这些变量：

export OTEL_SERVICE_NAME="robot-alert-service"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_TRACES_SAMPLER="parentbased_always_on"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=staging"

4.4 环境变量与 SDK 初始化流程

下图展示了从环境变量读取到 SDK 初始化完成的完整数据流，帮助你理解配置生效的底层逻辑：

4.5 验证配置是否生效

完成安装与环境变量设置后，运行以下 Python 脚本验证 SDK 能否正确加载配置并创建 Tracer：

# verify_otel.py
import os
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

# 读取环境变量并打印
print(f"OTEL_SERVICE_NAME: {os.getenv('OTEL_SERVICE_NAME', 'NOT SET')}")
print(f"OTEL_EXPORTER_OTLP_ENDPOINT: {os.getenv('OTEL_EXPORTER_OTLP_ENDPOINT', 'NOT SET')}")

# 初始化 TracerProvider
provider = TracerProvider()
trace.set_tracer_provider(provider)

# 获取 Tracer 并创建测试 Span
tracer = trace.get_tracer("verify-tracer")
with tracer.start_as_current_span("test-span") as span:
    span.set_attribute("test.key", "hello-otel")
    print(f"Span created: {span.get_span_context().span_id}")

print("SDK 初始化成功，环境变量配置正确。")

执行命令：

python verify_otel.py

预期输出示例：

OTEL_SERVICE_NAME: robot-alert-service
OTEL_EXPORTER_OTLP_ENDPOINT: http://localhost:4317
Span created: 1234567890abcdef
SDK 初始化成功，环境变量配置正确。

  生产环境建议：
  使用 .env 文件配合 python-dotenv 管理环境变量，避免在 shell 配置中硬编码。
在 Kubernetes 中通过 ConfigMap 或 Secret 注入环境变量，确保配置与代码分离。
始终设置 OTEL_RESOURCE_ATTRIBUTES 中的 deployment.environment，便于在链路中区分开发/测试/生产环境。

4.6 常见问题排查

问题现象	可能原因	解决方案
导入 `opentelemetry` 报 ModuleNotFoundError	未在虚拟环境中安装，或安装到了错误的 Python 解释器	确认 `which python` 指向虚拟环境路径，重新执行 `pip install`
环境变量读取为 None	变量未 export，或 export 后未 source	执行 `export OTEL_SERVICE_NAME="test"` 后，用 `echo $OTEL_SERVICE_NAME` 验证
gRPC 连接失败	Collector 未启动或端口错误	检查 `OTEL_EXPORTER_OTLP_ENDPOINT` 地址，使用 `telnet` 测试端口连通性
Span 未导出	未配置 Exporter 或采样率为 0	确认 `OTEL_TRACES_SAMPLER` 为 `parentbased_always_on`，且 Exporter 已注册