Semantic convention groups

状态: 开发中

Span、metric、event 和 resource 在 YAML schema 的语义约定组中定义。每个组都有一个 type 属性，可以是以下之一：

• span - 定义特定类型 span 的语义约定，例如 HTTP CLIENT
• metric - 定义特定 metric 的语义约定，例如 HTTP 客户端请求持续时间
• event - 定义特定 event 的语义约定，例如 exception。
• entity - 定义遥测数据收集所在的特定实体的语义约定，例如 service。

类型为 attribute_group 的组不描述语义约定，而是用于辅助目的。

所有语义约定组都具有以下通用属性：

• id - 在其他 span、instrument 或 event 中标识特定的 span 类型、metric instrument 或 event。
• brief 和 note 提供约定的人类可读描述。
• stability 描述了约定的成熟度级别。
• deprecated 属性标记该约定为已弃用，并提供有关替换或其他详细信息的信息。
• attributes 列出了指向 注册表 中适用属性的引用。

除了通用属性外，语义约定组还具有特定于类型的属性，请参阅 Schema 文档 以了解详细信息。

组的稳定性

语义约定组可以具有以下 稳定性级别：development、alpha、beta、release_candidate 和 stable。

除了 attribute_group 类型外，所有类型的组都需要指定稳定性级别。如果未指定稳定性级别，则默认为 development。

组的稳定性级别不得从 stable 更改为任何其他级别。

为保留对旧版 instrumentations 的代码生成和文档，语义约定组的任何稳定性级别不得被移除。

当组被重命名或不再推荐时，应将其标记为deprecated（已弃用）。

有关不同类型语义约定组所提供的稳定性保证的详细信息，请参阅 版本控制和稳定性。

稳定性保证不适用于 attribute_group 类型的组，因为它们不描述遥测项。

具有混合稳定性的组

组的稳定性保证适用于组的属性（如 type、id 和特定于信号的属性），以及该组引用的 stable 属性的覆盖属性。

组级别的稳定性保证不适用于不稳定的属性引用。

不稳定的组

• 可以添加或删除对 stable 或 unstable 属性的引用。
• 可以更改属性引用的必需级别和其他属性。

稳定的组

• 可以添加或删除具有 opt_in 必需级别的 unstable 属性的引用。
• 不应引用必需级别不是 opt_in 的 unstable 属性。当 unstable 属性变为 stable 时，可以更改 unstable 属性引用的必需级别，前提是 版本控制和稳定性 允许。
• 不得删除对 stable 属性的引用。

默认情况下，Stable instrumentations不得报告遵循语义约定不稳定部分的遥测数据。它们可以支持不稳定的部分，并允许用户选择加入。