Skip to content
OpenTelemetry 接入文档

OpenTelemetry 环境变量配置

OpenTelemetry 支持通过环境变量进行配置，这是最灵活和推荐的配置方式。本文档列出所有常用的环境变量及其说明。

通用配置

服务基本信息

OTEL_SERVICE_NAME

说明: 服务名称，用于标识您的应用程序。

类型: String

必需: 是

默认值: unknown_service

示例:

export OTEL_SERVICE_NAME=user-service

OTEL_RESOURCE_ATTRIBUTES

说明: 资源属性，以逗号分隔的键值对。

类型: String (key1=value1,key2=value2)

必需: 否

示例:

export OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3,deployment.environment=production,service.namespace=backend

常用属性:

  • service.version: 服务版本
  • service.namespace: 服务命名空间
  • service.instance.id: 实例 ID
  • deployment.environment: 部署环境（dev/test/staging/production）
  • host.name: 主机名
  • cloud.provider: 云服务商（aws/azure/gcp）
  • cloud.region: 云区域
  • k8s.namespace.name: Kubernetes 命名空间
  • k8s.pod.name: Pod 名称
  • k8s.deployment.name: Deployment 名称

日志级别

OTEL_LOG_LEVEL

说明: OpenTelemetry SDK 的日志级别。

类型: String

可选值: none, error, warn, info, debug

默认值: info

示例:

export OTEL_LOG_LEVEL=debug  # 开发环境
export OTEL_LOG_LEVEL=warn   # 生产环境

OTLP Exporter 配置

通用 OTLP 配置

OTEL_EXPORTER_OTLP_ENDPOINT

说明: OTLP exporter 的 endpoint 地址，同时用于 traces、metrics 和 logs。

类型: String (URL)

必需: 是（如果使用 OTLP）

默认值: http://localhost:4317 (gRPC) 或 http://localhost:4318 (HTTP)

示例:

# gRPC
export OTEL_EXPORTER_OTLP_ENDPOINT=uptrace-grpc.yodao.cn:4317


# HTTP
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.uptrace.dev:4318

注意:

  • 对于 gRPC，不要在路径后添加 /v1/traces 等路径
  • 对于 HTTP，路径会自动添加（如 /v1/traces）

OTEL_EXPORTER_OTLP_PROTOCOL

说明: OTLP exporter 使用的协议。

类型: String

可选值: grpc, http/protobuf, http/json

默认值: grpc

示例:

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

推荐:

  • 生产环境推荐使用 grpc，性能更好
  • 如果网络环境限制 gRPC，使用 http/protobuf

OTEL_EXPORTER_OTLP_HEADERS

说明: OTLP exporter 的 HTTP headers，用于认证等。

类型: String (key1=value1,key2=value2)

必需: 取决于后端要求

示例:

# Uptrace
export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://token@uptrace-grpc.yodao.cn/project


# API Key
export OTEL_EXPORTER_OTLP_HEADERS=api-key=your-api-key


# 多个 Headers
export OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer token,x-api-key=key123

OTEL_EXPORTER_OTLP_TIMEOUT

说明: OTLP exporter 请求超时时间（毫秒）。

类型: Integer

默认值: 10000 (10 秒)

示例:

export OTEL_EXPORTER_OTLP_TIMEOUT=15000  # 15 秒

OTEL_EXPORTER_OTLP_COMPRESSION

说明: OTLP exporter 的压缩算法。

类型: String

可选值: none, gzip

默认值: none

示例:

export OTEL_EXPORTER_OTLP_COMPRESSION=gzip

推荐: 对于大流量应用，启用 gzip 压缩可以减少网络带宽。

Traces 专用配置

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

说明: Traces 专用的 endpoint，覆盖通用 endpoint。

类型: String (URL)

示例:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://traces.example.com:4317

OTEL_EXPORTER_OTLP_TRACES_HEADERS

说明: Traces 专用的 headers，覆盖通用 headers。

类型: String

示例:

export OTEL_EXPORTER_OTLP_TRACES_HEADERS=api-key=traces-key

OTEL_EXPORTER_OTLP_TRACES_PROTOCOL

说明: Traces 专用的协议。

类型: String

可选值: grpc, http/protobuf

示例:

export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=grpc

OTEL_EXPORTER_OTLP_TRACES_TIMEOUT

说明: Traces 专用的超时时间（毫秒）。

类型: Integer

示例:

export OTEL_EXPORTER_OTLP_TRACES_TIMEOUT=10000

OTEL_EXPORTER_OTLP_TRACES_COMPRESSION

说明: Traces 专用的压缩算法。

类型: String

可选值: none, gzip

示例:

export OTEL_EXPORTER_OTLP_TRACES_COMPRESSION=gzip

Metrics 专用配置

OTEL_EXPORTER_OTLP_METRICS_ENDPOINT

说明: Metrics 专用的 endpoint。

类型: String (URL)

示例:

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://metrics.example.com:4317

OTEL_EXPORTER_OTLP_METRICS_HEADERS

说明: Metrics 专用的 headers。

类型: String

示例:

export OTEL_EXPORTER_OTLP_METRICS_HEADERS=api-key=metrics-key

OTEL_EXPORTER_OTLP_METRICS_PROTOCOL

说明: Metrics 专用的协议。

类型: String

可选值: grpc, http/protobuf

示例:

export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=grpc

OTEL_EXPORTER_OTLP_METRICS_TIMEOUT

说明: Metrics 专用的超时时间（毫秒）。

类型: Integer

示例:

export OTEL_EXPORTER_OTLP_METRICS_TIMEOUT=10000

OTEL_EXPORTER_OTLP_METRICS_COMPRESSION

说明: Metrics 专用的压缩算法。

类型: String

可选值: none, gzip

示例:

export OTEL_EXPORTER_OTLP_METRICS_COMPRESSION=gzip

Logs 专用配置

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT

说明: Logs 专用的 endpoint。

类型: String (URL)

示例:

export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.example.com:4317

OTEL_EXPORTER_OTLP_LOGS_HEADERS

说明: Logs 专用的 headers。

类型: String

示例:

export OTEL_EXPORTER_OTLP_LOGS_HEADERS=api-key=logs-key

OTEL_EXPORTER_OTLP_LOGS_PROTOCOL

说明: Logs 专用的协议。

类型: String

可选值: grpc, http/protobuf

示例:

export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc

OTEL_EXPORTER_OTLP_LOGS_TIMEOUT

说明: Logs 专用的超时时间（毫秒）。

类型: Integer

示例:

export OTEL_EXPORTER_OTLP_LOGS_TIMEOUT=10000

OTEL_EXPORTER_OTLP_LOGS_COMPRESSION

说明: Logs 专用的压缩算法。

类型: String

可选值: none, gzip

示例:

export OTEL_EXPORTER_OTLP_LOGS_COMPRESSION=gzip

Traces 配置

OTEL_TRACES_EXPORTER

说明: Traces exporter 的类型。

类型: String

可选值: otlp, jaeger, zipkin, console, none

默认值: otlp

示例:

export OTEL_TRACES_EXPORTER=otlp

OTEL_TRACES_SAMPLER

说明: Traces 采样器类型。

类型: String

可选值:

  • always_on: 采样所有 traces
  • always_off: 不采样任何 traces
  • traceidratio: 基于 trace ID 的概率采样
  • parentbased_always_on: 父级采样 + 总是采样
  • parentbased_always_off: 父级采样 + 从不采样
  • parentbased_traceidratio: 父级采样 + 概率采样（推荐）

默认值: parentbased_always_on

示例:

# 10% 采样率
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1


# 100% 采样（开发环境）
export OTEL_TRACES_SAMPLER=always_on

OTEL_TRACES_SAMPLER_ARG

说明: 采样器参数，对于 traceidratio 表示采样率（0.0 ~ 1.0）。

类型: Float

默认值: 1.0

示例:

export OTEL_TRACES_SAMPLER_ARG=0.1   # 10% 采样
export OTEL_TRACES_SAMPLER_ARG=0.01  # 1% 采样
export OTEL_TRACES_SAMPLER_ARG=1.0   # 100% 采样

推荐采样率:

  • 开发环境: 1.0 (100%)
  • 测试环境: 0.5 (50%)
  • 生产环境（低流量）: 0.5 (50%)
  • 生产环境（中等流量）: 0.1 (10%)
  • 生产环境（高流量）: 0.01 (1%)

OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT

说明: 每个 Span 的最大属性数量。

类型: Integer

默认值: 128

示例:

export OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT=256

OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT

说明: Span 属性值的最大长度。

类型: Integer

默认值: 无限制（某些 SDK 默认 1024）

示例:

export OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT=4096

OTEL_SPAN_EVENT_COUNT_LIMIT

说明: 每个 Span 的最大事件数量。

类型: Integer

默认值: 128

示例:

export OTEL_SPAN_EVENT_COUNT_LIMIT=256

说明: 每个 Span 的最大链接数量。

类型: Integer

默认值: 128

示例:

export OTEL_SPAN_LINK_COUNT_LIMIT=256

OTELBSP* (Batch Span Processor)

OTEL_BSP_SCHEDULE_DELAY

说明: 批量导出的时间间隔（毫秒）。

类型: Integer

默认值: 5000 (5 秒)

示例:

export OTEL_BSP_SCHEDULE_DELAY=3000  # 3 秒

OTEL_BSP_EXPORT_TIMEOUT

说明: 批量导出的超时时间（毫秒）。

类型: Integer

默认值: 30000 (30 秒)

示例:

export OTEL_BSP_EXPORT_TIMEOUT=15000  # 15 秒

OTEL_BSP_MAX_QUEUE_SIZE

说明: Span 队列的最大大小。

类型: Integer

默认值: 2048

示例:

export OTEL_BSP_MAX_QUEUE_SIZE=4096

OTEL_BSP_MAX_EXPORT_BATCH_SIZE

说明: 单次导出的最大 Span 数量。

类型: Integer

默认值: 512

示例:

export OTEL_BSP_MAX_EXPORT_BATCH_SIZE=1024

Metrics 配置

OTEL_METRICS_EXPORTER

说明: Metrics exporter 的类型。

类型: String

可选值: otlp, prometheus, console, none

默认值: otlp

示例:

export OTEL_METRICS_EXPORTER=otlp

OTEL_METRIC_EXPORT_INTERVAL

说明: Metrics 导出间隔（毫秒）。

类型: Integer

默认值: 60000 (60 秒)

示例:

export OTEL_METRIC_EXPORT_INTERVAL=30000  # 30 秒

OTEL_METRIC_EXPORT_TIMEOUT

说明: Metrics 导出超时时间（毫秒）。

类型: Integer

默认值: 30000 (30 秒)

示例:

export OTEL_METRIC_EXPORT_TIMEOUT=15000  # 15 秒

Logs 配置

OTEL_LOGS_EXPORTER

说明: Logs exporter 的类型。

类型: String

可选值: otlp, console, none

默认值: otlp

示例:

export OTEL_LOGS_EXPORTER=otlp

OTELBLRP* (Batch Log Record Processor)

OTEL_BLRP_SCHEDULE_DELAY

说明: 批量导出日志的时间间隔（毫秒）。

类型: Integer

默认值: 1000 (1 秒)

示例:

export OTEL_BLRP_SCHEDULE_DELAY=2000  # 2 秒

OTEL_BLRP_EXPORT_TIMEOUT

说明: 批量导出日志的超时时间（毫秒）。

类型: Integer

默认值: 30000 (30 秒)

示例:

export OTEL_BLRP_EXPORT_TIMEOUT=15000  # 15 秒

OTEL_BLRP_MAX_QUEUE_SIZE

说明: 日志队列的最大大小。

类型: Integer

默认值: 2048

示例:

export OTEL_BLRP_MAX_QUEUE_SIZE=4096

OTEL_BLRP_MAX_EXPORT_BATCH_SIZE

说明: 单次导出的最大日志数量。

类型: Integer

默认值: 512

示例:

export OTEL_BLRP_MAX_EXPORT_BATCH_SIZE=1024

Propagators 配置

OTEL_PROPAGATORS

说明: Context propagation 使用的传播器列表。

类型: String (逗号分隔)

可选值: tracecontext, baggage, b3, b3multi, jaeger, xray, ottrace

默认值: tracecontext,baggage

示例:

# W3C Trace Context (推荐)
export OTEL_PROPAGATORS=tracecontext,baggage


# B3 格式（兼容 Zipkin）
export OTEL_PROPAGATORS=b3


# B3 多 Header 格式
export OTEL_PROPAGATORS=b3multi


# Jaeger 格式
export OTEL_PROPAGATORS=jaeger


# 混合使用
export OTEL_PROPAGATORS=tracecontext,b3,baggage

SDK 禁用配置

OTEL_SDK_DISABLED

说明: 完全禁用 OpenTelemetry SDK。

类型: Boolean

默认值: false

示例:

export OTEL_SDK_DISABLED=true  # 禁用 SDK

OTEL_TRACES_DISABLED (非标准)

说明: 仅禁用 Traces（某些 SDK 支持）。

类型: Boolean

示例:

export OTEL_TRACES_DISABLED=true

OTEL_METRICS_DISABLED (非标准)

说明: 仅禁用 Metrics（某些 SDK 支持）。

类型: Boolean

示例:

export OTEL_METRICS_DISABLED=true

完整配置示例

开发环境

# .env.development


# 服务信息
OTEL_SERVICE_NAME=my-service-dev
OTEL_RESOURCE_ATTRIBUTES=service.version=dev,deployment.environment=development


# OTLP Exporter
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc


# Traces
OTEL_TRACES_EXPORTER=otlp
OTEL_TRACES_SAMPLER=always_on
OTEL_TRACES_SAMPLER_ARG=1.0


# Metrics
OTEL_METRICS_EXPORTER=otlp
OTEL_METRIC_EXPORT_INTERVAL=30000


# Logs
OTEL_LOGS_EXPORTER=otlp


# 日志级别
OTEL_LOG_LEVEL=debug

测试环境

# .env.test


# 服务信息
OTEL_SERVICE_NAME=my-service-test
OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3-rc1,deployment.environment=test


# OTLP Exporter
OTEL_EXPORTER_OTLP_ENDPOINT=https://test.apm-platform.com:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=https://test-token@test.apm-platform.com/test-project
OTEL_EXPORTER_OTLP_COMPRESSION=gzip


# Traces
OTEL_TRACES_EXPORTER=otlp
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.5


# Metrics
OTEL_METRICS_EXPORTER=otlp
OTEL_METRIC_EXPORT_INTERVAL=60000


# Logs
OTEL_LOGS_EXPORTER=otlp


# 日志级别
OTEL_LOG_LEVEL=info

生产环境

# .env.production


# 服务信息
OTEL_SERVICE_NAME=my-service
OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3,deployment.environment=production,service.namespace=backend,cloud.provider=aws,cloud.region=us-east-1


# OTLP Exporter
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.apm-platform.com:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=https://prod-token@api.apm-platform.com/prod-project
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_TIMEOUT=15000


# Traces
OTEL_TRACES_EXPORTER=otlp
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1
OTEL_BSP_MAX_QUEUE_SIZE=4096
OTEL_BSP_MAX_EXPORT_BATCH_SIZE=1024
OTEL_BSP_SCHEDULE_DELAY=5000


# Metrics
OTEL_METRICS_EXPORTER=otlp
OTEL_METRIC_EXPORT_INTERVAL=60000


# Logs
OTEL_LOGS_EXPORTER=otlp
OTEL_BLRP_MAX_QUEUE_SIZE=4096
OTEL_BLRP_MAX_EXPORT_BATCH_SIZE=1024


# 日志级别
OTEL_LOG_LEVEL=warn


# Propagators
OTEL_PROPAGATORS=tracecontext,baggage

Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  template:
    spec:
      containers:
      - name: app
        image: my-service:latest
        env:
        - name: OTEL_SERVICE_NAME
          value: my-service
        - name: OTEL_RESOURCE_ATTRIBUTES
          value: service.version=1.2.3,deployment.environment=production
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: http://otel-collector:4317
        - name: OTEL_EXPORTER_OTLP_PROTOCOL
          value: grpc
        - name: OTEL_EXPORTER_OTLP_HEADERS
          valueFrom:
            secretKeyRef:
              name: apm-credentials
              key: otlp-headers
        - name: OTEL_TRACES_SAMPLER
          value: parentbased_traceidratio
        - name: OTEL_TRACES_SAMPLER_ARG
          value: "0.1"
        - name: OTEL_LOGS_EXPORTER
          value: otlp
        - name: OTEL_METRICS_EXPORTER
          value: otlp

语言特定环境变量

某些环境变量是特定语言的，请查看对应的语言文档：

优先级

环境变量的优先级（从高到低）：

  1. 代码配置: 在代码中显式设置
  2. 环境变量: 通过 export 或 .env 文件
  3. 默认值: SDK 的默认配置

示例:

// 代码配置（最高优先级）
tp := sdktrace.NewTracerProvider(
    sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.5)),
)


// 如果代码中没有设置，使用环境变量
// OTEL_TRACES_SAMPLER_ARG=0.1


// 如果都没有设置，使用默认值（1.0）

验证配置

检查环境变量

# 显示所有 OTEL_ 开头的环境变量
env | grep OTEL_


# 验证特定变量
echo $OTEL_SERVICE_NAME
echo $OTEL_EXPORTER_OTLP_ENDPOINT

测试连接

# 使用 curl 测试 OTLP endpoint
curl -v uptrace-grpc.yodao.cn:4317


# 使用 opentelemetry-collector-contrib 测试
docker run -it --rm \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=uptrace-grpc.yodao.cn:4317 \
  -e OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=<your-dsn> \
  otel/opentelemetry-collector-contrib:latest

下一步

现在您已经了解了所有环境变量配置，可以开始接入您的应用程序：

  1. Go 语言接入
  2. Python 接入
  3. Java 接入
  4. JavaScript 接入
  5. .NET 接入

参考资源

在Gitlab上编辑本文档