#SDK 变量

OpenTelemetry SDK 的行为由环境变量控制，这些变量用于配置 telemetry 收集、处理和导出的各个方面。Instrumentation 自定义资源允许你设置这些变量，以自定义已埋点应用生成和发送 telemetry 数据的方式。

#常见 SDK 环境变量

以下环境变量通常用于配置 OpenTelemetry SDK 的行为：

#服务标识

• OTEL_SERVICE_NAME - 定义服务的逻辑名称
• OTEL_RESOURCE_ATTRIBUTES - 以键值对形式指定附加资源属性

#导出器配置

• OTEL_TRACES_EXPORTER - 配置 trace 导出器（例如，otlp、jaeger、zipkin）
• OTEL_METRICS_EXPORTER - 配置 metrics 导出器（例如，otlp、prometheus）
• OTEL_LOGS_EXPORTER - 配置日志导出器（例如，otlp）

#OTLP Endpoint 配置

• OTEL_EXPORTER_OTLP_ENDPOINT - 为所有 signal 设置 OTLP endpoint
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - 专门为 traces 设置 OTLP endpoint
• OTEL_EXPORTER_OTLP_METRICS_ENDPOINT - 专门为 metrics 设置 OTLP endpoint
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT - 专门为日志设置 OTLP endpoint

#协议配置

• OTEL_EXPORTER_OTLP_PROTOCOL - 指定 OTLP 协议（grpc 或 http/protobuf）
• OTEL_EXPORTER_OTLP_TRACES_PROTOCOL - traces 的协议
• OTEL_EXPORTER_OTLP_METRICS_PROTOCOL - metrics 的协议

#在 Instrumentation CR 中配置 SDK 变量

你可以在 Instrumentation 自定义资源中设置 SDK 环境变量：

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: my-instrumentation
spec:
  env:
    - name: OTEL_RESOURCE_ATTRIBUTES
      value: deployment.environment.name=production
    - name: OTEL_TRACES_EXPORTER
      value: otlp
    - name: OTEL_METRICS_EXPORTER
      value: otlp
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: http://otel-collector:4318
    - name: OTEL_EXPORTER_OTLP_PROTOCOL
      value: http/protobuf

这些变量会自动注入到已埋点的应用容器中。

#采样配置

使用以下变量控制 trace 采样行为：

• OTEL_TRACES_SAMPLER - 采样策略（例如，always_on、always_off、traceidratio、parentbased_always_on）
• OTEL_TRACES_SAMPLER_ARG - 采样器参数（例如，traceidratio 的采样比例）

示例配置：

spec:
  env:
    - name: OTEL_TRACES_SAMPLER
      value: parentbased_traceidratio
    - name: OTEL_TRACES_SAMPLER_ARG
      value: "0.1"

此配置会在遵循父 span 采样决策的同时，对 10% 的 traces 进行采样。

#传播配置

配置上下文传播格式：

• OTEL_PROPAGATORS - 以逗号分隔的 propagator 列表（例如，tracecontext,baggage,b3）

示例：

spec:
  env:
    - name: OTEL_PROPAGATORS
      value: tracecontext,baggage

#批处理配置

控制 telemetry 数据在导出前的批处理方式：

• OTEL_BSP_SCHEDULE_DELAY - 批量导出之间的延迟间隔（毫秒）
• OTEL_BSP_EXPORT_TIMEOUT - 等待导出的最长时间（毫秒）
• OTEL_BSP_MAX_QUEUE_SIZE - 批处理队列的最大大小
• OTEL_BSP_MAX_EXPORT_BATCH_SIZE - 导出的最大批次大小

#日志配置

配置 SDK 日志行为：

• OTEL_LOG_LEVEL - SDK 日志级别（例如，debug、info、warn、error）

#变量优先级

当同一个变量在多个位置定义时，适用以下优先级顺序（从高到低）：

1. 在 pod 规范中直接定义的环境变量
2. 来自 Instrumentation CR 的环境变量
3. 来自 instrumentation library 的默认值