跳到主要内容

OpenTelemetry 环境变量配置

介绍​

OpenTelemetry是一个开源的观测性框架，用于生成、收集和导出遥测数据（如指标、日志和追踪）。环境变量配置是OpenTelemetry中一种灵活的配置方式，尤其适合在不同环境（开发、测试、生产）中快速切换配置，而无需修改代码。本指南将详细介绍常用的环境变量及其应用场景。

核心环境变量​

OpenTelemetry支持通过环境变量控制SDK的行为。以下是最常用的变量：

1. 服务标识​

  • OTEL_SERVICE_NAME：定义服务的名称（必填），例如：
    bash
    export OTEL_SERVICE_NAME="user-service"

2. 导出器配置​

  • OTEL_TRACES_EXPORTER：指定追踪数据的导出方式（如 console、otlp）：
    bash
    export OTEL_TRACES_EXPORTER="otlp"

3. 端点配置​

  • OTEL_EXPORTER_OTLP_ENDPOINT：设置OTLP导出器的目标地址：
    bash
    export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
提示

使用 console 导出器时，数据会直接打印到终端，适合本地调试。

实际案例​

场景：配置一个Python应用​

以下是通过环境变量配置Python应用的完整示例：

  1. 设置环境变量：

    bash
    export OTEL_SERVICE_NAME="payment-service"
    export OTEL_TRACES_EXPORTER="otlp"
    export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4317"

  2. Python代码（无需硬编码配置）：

    python
    from opentelemetry import trace
    from opentelemetry.sdk.trace import TracerProvider

    trace.set_tracer_provider(TracerProvider())
    tracer = trace.get_tracer(__name__)

    with tracer.start_as_current_span("process_payment"):
        print("Payment processed")

  3. 输出： 数据会自动发送到 otel-collector:4317。

进阶配置​

采样率控制​

通过 OTEL_TRACES_SAMPLER 和 OTEL_TRACES_SAMPLER_ARG 控制采样：

bash
export OTEL_TRACES_SAMPLER="parentbased_traceidratio"
export OTEL_TRACES_SAMPLER_ARG="0.5"  # 50%的请求会被采样

资源属性​

添加自定义资源标签（如版本、环境）：

bash
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.0,deploy.env=prod"

总结​

环境变量提供了一种解耦的配置方式，使得OpenTelemetry的部署更加灵活。关键优势包括：

  • 环境隔离：不同环境（开发/生产）使用不同变量。
  • 安全性：敏感信息（如端点）可通过环境变量注入，避免硬编码。
  • 标准化：遵循OpenTelemetry规范，跨语言一致。

延伸学习​

  1. 官方文档：OpenTelemetry Environment Variables Specification
  2. 练习：尝试在本地启动一个OpenTelemetry Collector，并通过环境变量将应用数据导出到它。
  3. 调试技巧：设置 OTEL_LOG_LEVEL=debug 查看详细日志。
警告

确保在生产环境中禁用 console 导出器，避免性能问题。