通用配置规范

状态：稳定，除非另有说明

本规范的目的是描述适用于所有 OpenTelemetry SDK 配置源的通用指南。

实现可以根据本规范中的任何配置源来选择配置，但并非强制要求。如果它们这样做，则应遵循本文档中的指南。

特定类型指南

数值

接受数值的配置源分为

• 整数
• Duration
• 超时

以下指南适用于所有数值类型。

以下段落在稳定后添加，因此要求被限定为“应”（SHOULD），以允许实现避免破坏性更改。对于新实现，这些应被视为“必须”（MUST）要求。

对于接受数值的源，如果用户提供的值超出了配置项的有效范围，实现应生成警告并优雅地忽略该设置，即将其视为未设置。特别是，实现不应为负值分配自定义解释（例如，如果负值不自然地适用于配置且没有明确指定的含义），而应将其视为任何其他无效值。

例如，指定缓冲区大小的值自然必须为非负数。将负值解释为“缓冲所有内容”将是这种不推荐的自定义解释的一个例子。相反，应使用默认缓冲区大小。

请注意，即使自定义解释与默认值相同，这仍可能产生影响，因为它可能会重置从其他配置源设置的值（使用默认值）。

整数

如果实现选择支持整数值配置源，则应支持 0 到 2³¹ − 1（含）之间的非负值。各个 SDK 可以选择支持更大的值范围。

持续时间

任何表示持续时间的值都必须是一个整数，代表毫秒数。该值为非负数 - 如果提供负值，实现必须生成警告，优雅地忽略设置，并使用默认值（如果已定义）。

例如，值 12000 表示 12000 毫秒，即 12 秒。

超时

超时值类似于持续时间值，但由于它们解释超时零值的差异（见下文），因此被视为一个单独的类型。

任何表示超时的值都必须是一个整数，代表毫秒数。该值为非负数 - 如果提供负值，实现必须生成警告，优雅地忽略设置，并使用默认值（如果已定义）。

例如，值 12000 表示 12000 毫秒，即 12 秒。

实现应将超时零值（即 0 表示 0 毫秒）解释为无限制（即无限）。实际上，实现可以会将无限制解释为“非常长的时间”，并替换为一个非常大的持续时间（例如，32 位整数可表示的最大毫秒数）。

字符串

字符串值分为

• 枚举.

通常，字符串值包含描述实现如何解释它们的注释。

枚举

对于接受一组已知值（即枚举值）的配置源，实现可以支持此处未列出的其他值。

在报告配置错误时，实现应显示用户提供的原始值以帮助调试。

如果空对象（无操作）值可接受，则表示它的枚举值必须是 "none"。