配置数据模型

状态: 开发中

概述

OpenTelemetry 配置数据模型是 声明式配置接口 的一部分。

该数据模型定义了数据结构，允许用户指定 OpenTelemetry SDK 组件和仪器的预期配置。

数据模型在 opentelemetry-configuration 中使用 JSON Schema 定义。

数据模型本身是一个具有多种内置表示形式的抽象。

• 基于文件的配置模型
• SDK 内存中配置模型

版本策略和稳定性保证

请参阅 opentelemetry-configuration 的 版本策略。

基于文件的配置模型

配置文件是配置数据模型的序列化文件表示。

配置文件应使用以下序列化格式之一

• YAML 文件格式

YAML 文件格式

YAML 配置文件应遵循 YAML 规范修订版 >= 1.2。

YAML 配置文件应使用 v1.2 YAML 核心模式 进行解析。

YAML 配置文件必须使用文件扩展名 .yaml 或 .yml。

环境变量替换

配置文件支持环境变量替换，其引用方式使用 增强巴科斯范式 (Augmented Backus-Naur Form)

SUBSTITUTION-REF = "${" ["env:"] ENV-NAME [":-" DEFAULT-VALUE] "}"; valid substitution reference
INVALID-SUBSTITUTION-REF = "${" *(VCHAR-WSP-NO-RBRACE) "}"; invalid substitution reference

ENV-NAME = (ALPHA / "_") *(ALPHA / DIGIT / "_"); the name of the variable to be substituted
DEFAULT-VALUE = *(VCHAR-WSP-NO-RBRACE); any number of VCHAR-WSP-NO-RBRACE
VCHAR-WSP-NO-RBRACE = %x21-7C / "~" / WSP; printable chars and whitespace, except }

ALPHA = %x41-5A / %x61-7A; A-Z / a-z
DIGIT = %x30-39 ; 0-9

SUBSTITUTION-REF 定义了一个有效的环境变量替换引用

• 必须以 ${ 开头
• 可选后跟 env:
• 必须后跟 REF-NAME，即要替换的环境变量的名称
  • 必须以字母或 _ 字符开头
  • 必须后跟任意数量的字母数字字符或 _
• 可选后跟默认值
  • 必须以 :- 开头
  • 必须后跟 DEFAULT-VALUE，即任意数量的可打印字符和空格，但 } 除外
• 必须后跟 }

INVALID-SUBSTITUTION-REF 定义了一个无效的环境变量替换引用

• 必须以 ${ 开头
• 必须后跟任意数量的可打印字符和空格，但 } 除外
• 必须后跟 }

为了方便起见，SUBSTITUTION-REF 和 INVALID-SUBSTITUTION-REF 在下面用 PCRE2 正则表达式表示。请注意，这些表达式是非规范性的。

// SUBSTITUTION-REF
\$\{(?:env:)?(?<ENV-NAME>[a-zA-Z_][a-zA-Z0-9_]*)(:-(?<DEFAULT-VALUE>[^\n]*))?\}

// INVALID-SUBSTITUTION-REF
\$\{(?<INVALID_IDENTIFIER>[^}]+)\}

例如，${API_KEY} 和 ${env:API_KEY} 是有效的，而 ${1API_KEY} 和 ${API_$KEY} 是无效的。

环境变量替换**必须**仅应用于标量值。映射的键不能被替换。

SUBSTITUTION-REF 的 DEFAULT-VALUE 组件是一个可选的备用值，当 ENV-NAME 为 null、空或未定义时进行替换。如果引用的环境变量未定义且没有 DEFAULT-VALUE，则**必须**将其替换为空值。

$ 字符是转义序列，因此输入中的 $$ 将被转换为单个 $。转义序列解析出的 $ **不得**在输入与环境变量替换正则表达式匹配时被考虑。例如，$${API_KEY} 解析为 ${API_KEY}，并且 API_KEY 环境变量的值**不会**被替换。有关更多示例，请参见下表。实际上，这意味着解析器从左到右消耗输入，依次识别下一个转义序列，并将自前一个转义序列以来的内容与 SUBSTITUTION-REF 进行匹配。

例如，处理输入 $${FOO} ${BAR} $${BAZ}（其中 FOO=a, BAR=b, BAZ=c）的伪代码如下：

• 识别索引 0 处的转义序列 $$。对 input.substring(0, 0)="" 执行替换 => "" 并追加到输出。将 $ 追加到输出。当前输出："$"。
• 识别索引 15 处的转义序列 $$。对 input.substring(0+2, 15)="{FOO} ${BAR} " 执行替换 => "{FOO} b " 并追加到输出。将 $ 追加到输出。当前输出："${FOO} b $"。
• 到达输入末尾，无转义序列。对 input.substring(15+2, input.length)="{BAZ}" 执行替换 => "{BAZ}" 并追加到输出。返回输出："${FOO} b ${BAZ}"。

在解析包含不匹配 SUBSTITUTION-REF 但匹配 INVALID-SUBSTITUTION-REF 的引用时，解析器必须返回空结果（不允许部分结果）并向用户报告描述解析失败的错误。

节点类型**必须**在环境变量替换之后进行解释。这可以确保布尔值、整数或浮点属性的环境字符串表示能够正确转换为预期的类型。

**不得**通过环境变量注入 YAML 结构。例如，请参阅下面对 INVALID_MAP_VALUE 环境变量的引用。

**不得**通过环境变量注入其他环境变量。例如，请参阅下面对 DO_NOT_REPLACE_ME 环境变量的引用。

下表展示了各种输入的环境变量替换行为。示例假设环境变量设置如下：

export STRING_VALUE="value"
export BOOL_VALUE="true"
export INT_VALUE="1"
export FLOAT_VALUE="1.1"
export HEX_VALUE="0xdeadbeef"                   # A valid integer value (i.e. 3735928559) written in hexadecimal
export INVALID_MAP_VALUE="value\nkey:value"     # An invalid attempt to inject a map key into the YAML
export DO_NOT_REPLACE_ME="Never use this value" # An unused environment variable
export REPLACE_ME='${DO_NOT_REPLACE_ME}'        # A valid replacement text, used verbatim, not replaced with "Never use this value"
export VALUE_WITH_ESCAPE='value$$'              # A valid variable substituted without escaping