Attribute requirement levels

状态: 稳定

本节适用于日志、指标、资源和 Span，并描述了语义约定中定义的属性的要求级别。

属性要求级别适用于Instrumentation Library。

属性的要求级别由语义约定根据属性在已仪器化的实体中的可用性、性能、安全性和其他因素来指定。在指定要求级别时，语义约定必须考虑特定信号的要求。

例如，可能具有高基数的指标属性只能定义为Opt-In（选择加入）级别。

引用另一个语义约定中的属性的语义约定，可以在其自身范围内修改该属性的要求级别。否则，将应用所引用语义约定中的要求级别。

例如，数据库语义约定引用了通用属性中定义的network.transport属性，并为其指定了Conditionally Required（有条件地必需）级别。

要求级别

下表详细说明了属性在遥测信号上的默认包含行为，以及是否可以通过配置选项进行更改。

[1]：除非属性要求条件或说明未满足。

[2]：除非它因推荐部分中所述的原因而被排除。

必需

所有仪器化都必须填充该属性。定义必需属性的语义约定期望绝大多数仪器化库和应用程序都能够有效地检索和填充它，并且还可以满足约定定义的特定于信号的基数、安全性和其他要求。http.request.method是必需属性的一个示例。

注意：遥测的消费者可以通过检查Required属性是否存在来检测遥测项是否遵循特定的语义约定。例如，Span 上存在 db.system.name 属性可以作为该 Span 遵循数据库语义的指示。

有条件地必需

当满足给定条件时，所有仪器化都必须填充该属性。Conditionally Required属性的语义约定必须阐明要填充该属性的条件。

http.route是有条件地必需的属性的一个例子，当已仪器化的 HTTP 框架为已仪器化的请求提供路由信息时，该属性将被填充。一些低级 HTTP 服务器实现不支持路由，因此相应的仪器化无法填充该属性。

当Conditionally Required属性的条件不满足，并且没有填充该属性的要求时，语义约定可以提供如何处理该属性的特殊说明。如果未提供说明，并且仪器化能够填充该属性，则仪器化应在属性上使用Opt-In（选择加入）要求级别。

例如，server.address被一个约定指定为Conditionally Required。当只有服务器 IP 地址可用于仪器化时，仪器化可以执行 DNS 查询、缓存并填充server.address，但这只有在用户明确启用仪器化以这样做时才能进行，并且要考虑到 DNS 查询带来的性能问题。

推荐

如果属性易于获取且可以高效填充，仪器化应默认添加该属性。仪器化可以提供一个配置选项来禁用 Recommended 属性。

由于默认的性能、安全、隐私或其他考虑因素而不填充Recommended属性的仪器化，应允许用户选择加入以发出它们，这按照Opt-In（选择加入）要求级别定义（如果属性在逻辑上适用）。

选择加入

仅当用户配置仪器化以这样做时，仪器化才应填充该属性。不支持配置的仪器化不得填充Opt-In属性。

此属性要求级别推荐用于检索成本特别高或可能带来安全或隐私风险的属性。因此，这些属性应仅由做出知情决定的用户显式启用。

性能建议

以下是一些默认应避免的昂贵操作的示例：

• 当只有 IP 地址可供仪器化使用时，为填充server.address而进行的 DNS 查询。缓存查询结果并不能解决所有可能的情况，因此也应默认避免。
• 在 HTTP 框架计算路由之前强制进行http.route计算。
• 当Content-Length报头不可用时，读取响应流以查找http.response.body.size。