#SDK 变量

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

#常用 SDK 环境变量

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

#Service 标识

• OTEL_SERVICE_NAME - 定义 service 的逻辑名称
• OTEL_RESOURCE_ATTRIBUTES - 以键值对形式指定附加的 resource attributes

#Exporter 配置

• OTEL_TRACES_EXPORTER - 配置 trace exporter（例如 otlp、jaeger、zipkin）
• OTEL_METRICS_EXPORTER - 配置 metrics exporter（例如 otlp、prometheus）
• OTEL_LOGS_EXPORTER - 配置日志 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

#Protocol 配置

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

#在 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

这些变量会自动注入到已进行 instrumented 的应用容器中。

#采样配置

使用以下变量控制 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"

此配置会采样 10% 的 trace，同时遵循父 span 的采样决策。

#传播配置

配置上下文传播格式：

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

示例：

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

#Batch 处理配置

控制 telemetry 数据在导出前如何进行 batch 处理：

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

#日志配置

配置 SDK 日志行为：

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

#变量优先级

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

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