OpenTelemetry

使用 OTEL_* 环境变量配置 SDK

使用标准变量为任何语言设置服务名称、exporter、采样和限制。

10 min 初级

OpenTelemetry SDK 共享一组通用的环境变量,所以同样的配置适用于 Java、Python、Node.js、.NET 和其他语言。这是配置应用最常见的方式,并且它非常适合容器和 Kubernetes,因为环境是由平台设置的。本指南涵盖你最常用的变量。

每种语言的 SDK 按自己的节奏实现规范,所以请在你所用语言的文档中验证不太常见的变量。

必备项

export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=staging
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

OTEL_SERVICE_NAME 设置 service.name,这是最重要的属性,因为后端按它对一切分组。如果未设置,你会得到一个 unknown_service 名称。它优先于 OTEL_RESOURCE_ATTRIBUTES 内部的 service.name。
OTEL_RESOURCE_ATTRIBUTES 是以逗号分隔的 key=value 对列表,描述服务,例如它的版本和环境。
OTEL_EXPORTER_OTLP_ENDPOINT 是遥测数据的去向。把它指向一个 Collector。
OTEL_EXPORTER_OTLP_PROTOCOL 是 grpc、http/protobuf 或 http/json。

端点与协议:端口必须匹配

默认值是 HTTP 的 http://localhost:4318 和 gRPC 的 http://localhost:4317。对于 HTTP 协议,SDK 会在基础端点后追加 v1/traces、v1/metrics 和 v1/logs。如果你设置了按信号划分的端点,例如 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,它就会被原样使用,不追加任何内容。

最常见的错误是不匹配:把 gRPC 发送到 4318 端口,或把 HTTP 发送到 4317 端口。请把协议和端口一起选择。规范中的默认协议是 http/protobuf,但有些 SDK 默认使用 gRPC,所以请显式设置它。

选择 exporter

export OTEL_TRACES_EXPORTER=otlp      # default
export OTEL_METRICS_EXPORTER=otlp     # default
export OTEL_LOGS_EXPORTER=otlp        # default

取值包括 otlp、console(打印到终端,便于调试),以及用于关闭某种信号的 none。有些语言支持其他的,比如用于指标的 prometheus 或用于追踪的 zipkin。

OTLP exporter 选项

export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer abc123,x-tenant=team-a"
export OTEL_EXPORTER_OTLP_TIMEOUT=10000       # milliseconds in most SDKs
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/ssl/ca.pem
export OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE=/etc/ssl/client.pem
export OTEL_EXPORTER_OTLP_CLIENT_KEY=/etc/ssl/client.key

这些变量每一个都有按信号划分的变体,比如 OTEL_EXPORTER_OTLP_TRACES_TIMEOUT 或 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,它们优先于基础变量。HEADERS 是以逗号分隔的 key=value 对列表,所有值都是字符串。使用 https:// 端点启用 TLS,并为私有证书颁发机构或双向 TLS 使用证书变量。

传播与采样

export OTEL_PROPAGATORS=tracecontext,baggage    # default
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

OTEL_PROPAGATORS 决定哪些头部在服务之间携带追踪上下文。默认值是 tracecontext,baggage(W3C)。请求路径上的所有服务必须使用兼容的 propagator,否则追踪会在边界处断裂。只有在你必须与较旧的系统互操作时才添加 b3 或其他。
OTEL_TRACES_SAMPLER 默认是 parentbased_always_on,它记录一切并遵循调用方的决定。对于头部采样,parentbased_traceidratio 配合 OTEL_TRACES_SAMPLER_ARG=0.1 会保留约百分之十的新追踪,同时尊重父级的决定。采样指南介绍了何时改在 Collector 中采样。

批处理与限制

批处理设置控制内存使用和导出频率。来自规范的默认值:

变量	默认值
`OTEL_BSP_SCHEDULE_DELAY`	`5000` ms
`OTEL_BSP_MAX_QUEUE_SIZE`	`2048`
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	`512`
`OTEL_BSP_EXPORT_TIMEOUT`	`30000` ms
`OTEL_BLRP_SCHEDULE_DELAY`	`1000` ms
`OTEL_METRIC_EXPORT_INTERVAL`	`60000` ms
`OTEL_ATTRIBUTE_COUNT_LIMIT`	`128`
`OTEL_SPAN_EVENT_COUNT_LIMIT`	`128`

BSP 是 span 批处理器,BLRP 是日志记录批处理器。如果你看到负载下有 span 被丢弃,请提高队列大小;在测试期间降低指标间隔(例如 10000),这样你就不必为一个数据点等待一分钟。

运维开关

export OTEL_SDK_DISABLED=true     # turn telemetry off without removing instrumentation
export OTEL_LOG_LEVEL=debug       # the SDK's own diagnostic log level (default info)

OTEL_SDK_DISABLED 是一个快速的总开关。调试日志很啰嗦,所以不要在生产环境中一直开着它。

把它放进 Docker Compose 和 Kubernetes

Compose:

services:
  checkout:
    image: myorg/checkout:1.4.2
    environment:
      OTEL_SERVICE_NAME: checkout
      OTEL_RESOURCE_ATTRIBUTES: service.version=1.4.2,deployment.environment.name=staging
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
      OTEL_TRACES_SAMPLER: parentbased_traceidratio
      OTEL_TRACES_SAMPLER_ARG: "0.25"

Kubernetes:

env:
  - name: OTEL_SERVICE_NAME
    value: checkout
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://otel-collector.observability.svc.cluster.local:4318
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: k8s.pod.name=$(POD_NAME),deployment.environment.name=staging
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name

Operator 指南展示了如何用 Instrumentation 资源自动注入这些变量,这样应用团队就不必手工设置它们。

优先级顺序与陷阱

代码中的配置通常胜过环境变量,按信号划分的变量胜过通用变量。
你的 SDK 不识别的变量会被悄悄忽略。当某个设置似乎没有任何作用时,请查看该语言的配置页面。
不要把 secret 放进 OTEL_RESOURCE_ATTRIBUTES。它会成为每一条遥测数据上的标签。
当端点包含路径(例如在代理之后)时,请使用按信号划分的端点变量,这样就不会追加任何内容。
把每个服务的变量列表集中在一个地方(Compose 文件或 Helm values 文件),使变更得到审查。

完整列表请参见 SDK 环境变量规范和 OTLP exporter 配置。

RackMint