环境变量规范
状态：稳定，除非另有说明
本规范的目的是统一不同 OpenTelemetry 实现之间的环境变量名称和值解析。
实现 MAY 选择通过本规范中的环境变量进行配置，但并非必需。如果选择这样做，它们 SHOULD 使用本文档中指定的名称和值解析行为。它们还 SHOULD 遵循 通用配置规范。
实施指南
环境变量 MAY 由组件直接处理（实现），在 SDK 中处理，或者在单独的组件中处理（例如，基于环境的自动配置组件）。
基于环境的配置 MUST 有一个直接的代码配置等效项。
解析空值
SDK 必须将环境变量的空值解释为未设置该变量时的情况。
特定类型指导
布尔值
任何代表布尔值的值，只有在不区分大小写的字符串 "true" 时才被设置为 true，这意味着 "True" 或 "TRUE" 也被接受为 true。实现 MUST 不会扩展此定义并定义解释为 true 的其他值。任何未在此处明确定义为 true 值的值，包括未设置和空值，MUST 被解释为 false。如果使用非 true 值（不区分大小写的字符串 "false"、空值或未设置值）以外的任何值，则 SHOULD 记录警告，以告知用户已应用回退到 false。所有布尔环境变量 SHOULD 被命名和定义，使得 false 是预期的安全默认行为。重命名或更改默认值 MUST 不会在 major 版本升级前发生。
数值
以下指导适用于所有数值类型，并扩展了 通用配置规范“数值”指导。
在稳定化之后添加了以下段落，因此要求被限定为“SHOULD”，以允许实现避免破坏性更改。对于新的实现，这些应该被视为 MUST 要求。
对于接受数值的变量，如果用户提供了一个实现无法解析的值，实现 SHOULD 生成一个警告并优雅地忽略该设置，即将其视为未设置。
字符串
字符串值被细分为
- 枚举.
枚举
以下指导扩展了 通用配置规范“枚举”指导。
枚举值 SHOULD 被不区分大小写地解释。
对于接受枚举值的源，如果用户提供的值是实现不认识的，实现 MUST 生成一个警告并优雅地忽略该设置。
通用 SDK 配置
| 名称 | 描述 | 默认值 | 类型 | 注意 |
|---|---|---|---|---|
| OTEL_SDK_DISABLED | 禁用所有信号的 SDK | false | 布尔值 | 如果为“true”，则将为所有遥测信号使用无操作（no-op）的 SDK 实现。任何其他值或变量的缺失将没有影响，SDK 将保持启用状态。此设置对通过 OTEL_PROPAGATORS 变量配置的 propagators 没有影响。 |
| OTEL_ENTITIES | 要与资源关联的实体信息 | 字符串 | 有关更多详细信息，请参阅 Entities SDK。 | |
| OTEL_RESOURCE_ATTRIBUTES | 用作资源属性的键值对 | 有关详细信息，请参阅 资源语义约定。 | 字符串 | 有关更多详细信息，请参阅 Resource SDK。 |
| OTEL_SERVICE_NAME | 设置 service.name 资源属性的值 | 字符串 | 如果 service.name 也通过 OTEL_RESOURCE_ATTRIBUTES 提供，则 OTEL_SERVICE_NAME 具有优先权。 | |
| OTEL_LOG_LEVEL | 由 SDK 内部日志记录器 使用的日志级别 | “info” | 枚举 | |
| OTEL_PROPAGATORS | 用作逗号分隔列表的 Propagators | “tracecontext,baggage” | 枚举 | 值 MUST 被去重，以便只注册一次 Propagator。 |
| OTEL_TRACES_SAMPLER | 用于 traces 的 Sampler | “parentbased_always_on” | 枚举 | 请参阅 Sampling |
| OTEL_TRACES_SAMPLER_ARG | 用作 Sampler 参数的值 | 参见脚注 | 指定的 Value 仅在设置了 OTEL_TRACES_SAMPLER 时使用。每种 Sampler 类型定义了其自己的预期输入（如果有）。无效或未识别的输入 MUST 被记录，并且 MUST 被忽略，即实现 MUST 的行为如同 OTEL_TRACES_SAMPLER_ARG 未设置一样。 |
OTEL_PROPAGATORS 的已知值包括
"tracecontext"： W3C Trace Context"baggage"： W3C Baggage"b3"： B3 Single"b3multi"： B3 Multi"jaeger"： Jaeger"xray"： AWS X-Ray (第三方)"ottrace"： OT Trace (第三方)"none"： 无自动配置的 propagator。
OTEL_TRACES_SAMPLER 的已知值包括
"always_on"：AlwaysOnSampler"always_off"：AlwaysOffSampler"traceidratio"：TraceIdRatioBased"parentbased_always_on"：ParentBased(root=AlwaysOnSampler)"parentbased_always_off"：ParentBased(root=AlwaysOffSampler)"parentbased_traceidratio"：ParentBased(root=TraceIdRatioBased)"parentbased_jaeger_remote"：ParentBased(root=JaegerRemoteSampler)"jaeger_remote"：JaegerRemoteSampler"xray"： AWS X-Ray 集中采样 (第三方)
根据 OTEL_TRACES_SAMPLER 的值，OTEL_TRACES_SAMPLER_ARG 可以设置如下
- 对于
traceidratio和parentbased_traceidratiosamplers：采样概率，范围在 [0..1] 内的数字，例如“0.25”。如果未设置，默认为 1.0。 - 对于
jaeger_remote和parentbased_jaeger_remote：该值是一个逗号分隔的列表endpoint： 格式为scheme://host:port的 gRPC 服务器端点，该服务器提供服务的采样策略（sampling.proto）。pollingIntervalMs：以毫秒为单位，表示采样器轮询后端以获取采样策略更新的频率。initialSamplingRate：在 [0..1] 范围内的值，当后端无法访问以检索采样策略时，用作采样概率。一旦成功检索到采样策略，此值将不再生效，因为将使用远程策略，直到检索到新的更新。- 示例：
endpoint=https://:14250,pollingIntervalMs=5000,initialSamplingRate=0.25
批量 Span Processor
| 名称 | 描述 | 默认值 | 类型 | 注意 |
|---|---|---|---|---|
| OTEL_BSP_SCHEDULE_DELAY | 两次连续导出之间的延迟间隔（以毫秒为单位） | 5000 | Duration | |
| OTEL_BSP_EXPORT_TIMEOUT | 导出数据允许的最大时间（以毫秒为单位） | 30000 | 超时 | |
| OTEL_BSP_MAX_QUEUE_SIZE | 最大队列大小 | 2048 | 整数 | 有效值为正数。 |
| OTEL_BSP_MAX_EXPORT_BATCH_SIZE | 最大批次大小 | 512 | 整数 | 必须小于或等于 OTEL_BSP_MAX_QUEUE_SIZE。有效值为正数。 |
批量 LogRecord Processor
| 名称 | 描述 | 默认值 | 类型 | 注意 |
|---|---|---|---|---|
| OTEL_BLRP_SCHEDULE_DELAY | 两次连续导出之间的延迟间隔（以毫秒为单位） | 1000 | Duration | |
| OTEL_BLRP_EXPORT_TIMEOUT | 导出数据允许的最大时间（以毫秒为单位） | 30000 | 超时 | |
| OTEL_BLRP_MAX_QUEUE_SIZE | 最大队列大小 | 2048 | 整数 | 有效值为正数。 |
| OTEL_BLRP_MAX_EXPORT_BATCH_SIZE | 最大批次大小 | 512 | 整数 | 必须小于或等于 OTEL_BLRP_MAX_QUEUE_SIZE。有效值为正数。 |
属性限制
Implementations SHOULD only offer environment variables for the types of attributes, for which that SDK implements truncation mechanism.
有关限制的定义，请参阅 SDK 的 Attribute Limits 部分。
| 名称 | 描述 | 默认值 | 类型 | 注意 |
|---|---|---|---|---|
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | 允许的最大属性值大小 | 无限制 | 整数 | 有效值为非负数。 |
| OTEL_ATTRIBUTE_COUNT_LIMIT | 允许的最大属性数量 | 128 | 整数 | 有效值为非负数。 |
Span 限制
有关限制的定义，请参阅 SDK 的 Span Limits 部分。
| 名称 | 描述 | 默认值 | 类型 | 注意 |
|---|---|---|---|---|
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | 允许的最大属性值大小 | 无限制 | 整数 | 有效值为非负数。 |
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | 允许的最大 Span 属性数量 | 128 | 整数 | 有效值为非负数。 |
| OTEL_SPAN_EVENT_COUNT_LIMIT | 允许的最大 Span 事件数量 | 128 | 整数 | 有效值为非负数。 |
| OTEL_SPAN_LINK_COUNT_LIMIT | 允许的最大 Span 链接数量 | 128 | 整数 | 有效值为非负数。 |
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | 每个 Span 事件允许的最大属性数量 | 128 | 整数 | 有效值为非负数。 |
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | 每个 Span 链接允许的最大属性数量 | 128 | 整数 | 有效值为非负数。 |
LogRecord 限制
有关限制的定义，请参阅 SDK 的 LogRecord Limits 部分。
| 名称 | 描述 | 默认值 | 类型 | 注意 |
|---|---|---|---|---|
| OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | 允许的最大属性值大小 | 无限制 | 整数 | 有效值为非负数。 |
| OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | 允许的最大 LogRecord 属性数量 | 128 | 整数 | 有效值为非负数。 |
OTLP Exporter
请参阅 OpenTelemetry Protocol Exporter 配置选项。
Zipkin Exporter
状态： 已弃用
| 名称 | 描述 | 默认值 | 类型 |
|---|---|---|---|
| OTEL_EXPORTER_ZIPKIN_ENDPOINT | Zipkin traces 的端点 | https://:9411/api/v2/spans | 字符串 |
| OTEL_EXPORTER_ZIPKIN_TIMEOUT | Zipkin exporter 在每次批量导出时等待的最大时间（以毫秒为单位） | 10000 | 超时 |
此外，以下环境变量保留供 Zipkin Exporter 配置在未来使用
OTEL_EXPORTER_ZIPKIN_PROTOCOL
这将用于指定导出器是使用 v1 还是 v2，json、thrift 或 protobuf。截至 1.0 规范，没有指定的默认值，也没有通过环境变量进行配置。
Prometheus Exporter
状态: 开发中
| 名称 | 描述 | 默认值 | 类型 |
|---|---|---|---|
| OTEL_EXPORTER_PROMETHEUS_HOST | Prometheus exporter 使用的主机 | “localhost” | 字符串 |
| OTEL_EXPORTER_PROMETHEUS_PORT | Prometheus exporter 使用的端口 | 9464 | 整数 |
Exporter 选择
我们定义了用于为每个信号设置一个或多个 exporter 的环境变量。
| 名称 | 描述 | 默认值 | 类型 |
|---|---|---|---|
| OTEL_TRACES_EXPORTER | 要使用的 Trace exporter | “otlp” | 枚举 |
| OTEL_METRICS_EXPORTER | 要使用的 Metrics exporter | “otlp” | 枚举 |
| OTEL_LOGS_EXPORTER | 要使用的 Logs exporter | “otlp” | 枚举 |
实现 MAY 接受逗号分隔的列表以启用设置多个 exporter。
OTEL_TRACES_EXPORTER 的已知值包括
"otlp"： OTLP"zipkin"： Zipkin (默认为 protobuf 格式)"console"： 标准输出"logging"： 标准输出。这是一个为向后兼容而保留的已弃用值。新实现 SHOULD 不支持它。"none"： 无自动配置的 trace exporter。
OTEL_METRICS_EXPORTER 的已知值包括
"otlp"： OTLP"prometheus"： Prometheus"console"： 标准输出"logging"： 标准输出。这是一个为向后兼容而保留的已弃用值。新实现 SHOULD 不支持它。"none"： 无自动配置的 metrics exporter。
OTEL_LOGS_EXPORTER 的已知值包括
"otlp"： OTLP"console"： 标准输出"logging"： 标准输出。这是一个为向后兼容而保留的已弃用值。新实现 SHOULD 不支持它。"none"： 无自动配置的 logs exporter。
开发中 Exporter 选择
状态: 开发中
除了上述之外，还为开发中的 Exporter 选择添加了以下环境变量
OTEL_TRACES_EXPORTER 的其他已知值包括
"otlp/stdout"： OTLP 文件写入标准输出
OTEL_METRICS_EXPORTER 的其他已知值包括
"otlp/stdout"： OTLP 文件写入标准输出
OTEL_LOGS_EXPORTER 的其他已知值包括
"otlp/stdout"： OTLP 文件写入标准输出
Metrics SDK 配置
Exemplar
| 名称 | 描述 | 默认值 | 类型 |
|---|---|---|---|
OTEL_METRICS_EXEMPLAR_FILTER | 过滤哪些测量值可以成为 Exemplars。 | "trace_based" | 枚举 |
OTEL_METRICS_EXEMPLAR_FILTER 的已知值包括
"always_on"： AlwaysOn"always_off"： AlwaysOff"trace_based"： TraceBased
定期导出 MetricReader
用于推送式 metrics exporter（OTLP、stdout、in-memory）的特定环境变量，这些 exporter 使用 periodic exporting MetricReader。
| 名称 | 描述 | 默认值 | 类型 |
|---|---|---|---|
OTEL_METRIC_EXPORT_INTERVAL | 两次导出尝试之间的间隔时间（以毫秒为单位）。 | 60000 | Duration |
OTEL_METRIC_EXPORT_TIMEOUT | 导出数据允许的最大时间（以毫秒为单位）。 | 30000 | 超时 |
声明式配置
状态: 开发中
涉及 声明式配置 的环境变量。
| 名称 | 描述 | 默认值 | 类型 | 注意 |
|---|---|---|---|---|
| OTEL_EXPERIMENTAL_CONFIG_FILE | 用于配置 SDK 的配置文件路径。如果设置，此文件中的配置将优先于所有其他 SDK 配置环境变量。 | 字符串 | 见下文 |
如果设置了 OTEL_EXPERIMENTAL_CONFIG_FILE，则使用指定路径的文件来调用 Parse。生成的 配置模型 用于调用 Create 以生成完全配置的 SDK 组件。
当设置 OTEL_EXPERIMENTAL_CONFIG_FILE 时，除了配置文件中用于 环境变量替换 的变量之外，所有其他环境变量都将被忽略。忽略环境变量是必要的，因为在所有情况下，没有直观的方法可以将扁平的环境变量方案与结构化的文件配置方案合并。鼓励需要合并多个配置源的用户在调用 Create 之前定制 Parse 返回的配置模型。例如，用户可以解析多个文件，并定义合并生成的配置模型的逻辑，或者将环境变量的值覆盖在配置模型之上。实现 MAY 提供一种机制来定制从 OTEL_EXPERIMENTAL_CONFIG_FILE 解析的配置模型。
鼓励用户使用 sdk-migration-config.yaml 作为 OTEL_EXPERIMENTAL_CONFIG_FILE 的起点。此文件代表常见的 SDK 配置场景，并包含对环境变量引用的环境变量替换，这些变量否则会被忽略。或者，sdk-config.yaml 提供了一个常见的 SDK 配置起点，没有环境变量替换引用。
TODO：弃用不兼容的环境变量（#3967）
语言特定环境变量
为了确保跨项目的命名一致性，本规范建议语言特定的环境变量使用以下约定形成
OTEL_{LANGUAGE}_{FEATURE}