遥测稳定性

状态: 开发中

本节定义了 OpenTelemetry 仪器产生的遥测数据的稳定性要求。

所有 OpenTelemetry 编写的仪器都将被标记为“不稳定”或“稳定”，从其产生的遥测数据的角度来看。

添加新的指标、跨度、跨度事件或日志记录，以及向跨度、跨度事件、日志记录或资源添加新属性，都被视为添加性、非破坏性更改，并且对于“不稳定”和“稳定”仪器始终是允许的。

已产生遥测数据的其他更改受以下规则的约束。

不稳定的仪器

不稳定的遥测生成仪器（简称不稳定仪器）SHOULD 通过仪器作者认为适合其语言的任何方式（例如，通过版本号、工件名称、文档等）清楚地标记。

不稳定仪器对它们产生的遥测数据的形状以及该形状如何随时间、从版本到版本发生变化不提供任何保证。跨度或指标名称、任何遥测项的属性都可能无限制地更改。已产生的遥测数据MAY 指定一个模式 URL（Schema URL），如果遥测数据符合特定模式。

OpenTelemetry 编写的不稳定仪器MAY 产生 OpenTelemetry 语义约定未描述的额外遥测数据。

TODO：决定是否需要在传输中指示已产生的遥测数据是否来自不稳定的仪器。

稳定的仪器

稳定的遥测生成仪器（简称稳定仪器）SHOULD 通过仪器作者认为适合其语言的任何方式（例如，通过版本号、工件名称、文档等）清楚地标记。

稳定的仪器分为两类：固定模式生成器和基于模式文件的生成器。

OpenTelemetry 编写的稳定仪器 SHOULD NOT 产生 OpenTelemetry 语义约定未描述的遥测数据。但是，如果违反此规则，仪器 MUST NOT 更改此类遥测数据，无论它们是固定模式生成器还是基于模式文件的生成器。一旦已产生的遥测数据被添加到语义约定中，更改将按如下所述允许。

固定模式遥测生成器

标记为“稳定”且未在已产生遥测数据中包含模式 URL 的仪器称为固定模式遥测生成器。

此类仪器被禁止更改任何已产生的遥测数据。如果规范随时间变化并且语义约定得到更新，仪器仍然被禁止采用这些更改。如果仪器希望采用语义约定更改，它必须首先通过在已产生遥测数据中添加适当的模式 URL，成为 基于模式文件的遥测生成器。

基于模式文件的遥测生成器

在已产生遥测数据中包含模式 URL 的稳定仪器称为基于模式文件的遥测生成器。

此类仪器在禁止依赖模式转换实现遥测数据稳定性的禁令解除之前，被禁止更改已产生的遥测数据，并且在此日期之前受到与 固定模式遥测生成器 完全相同的限制。

禁令解除后，如果满足以下所有条件，则允许稳定仪器更改已产生的遥测数据

• 更改是 OpenTelemetry 语义约定的一部分，并且存在于已发布的规范版本中。
• 该更改具有相应的 已发布 的 OpenTelemetry 模式文件，该文件描述了该更改。
• 已产生的遥测数据正确指定了相应的模式 URL。