otel-semantic-conventions

用途

本技能用于治理 OpenTelemetry 遥测属性与指标仪器的正确选择、放置和校验，使其符合 OpenTelemetry Semantic Conventions 规范。当需要选择、应用或审查遥测属性时使用。涉及 span 命名、span 类型和 span 状态码时，应参考 otel-instrumentation 技能。

Attribute Registry 是所有已定义属性的唯一事实来源。

主要能力

技能按规则组织，覆盖以下方面：

attributes：属性注册表、选择、放置，以及按领域划分的常见属性。适用于选择或审查属性；HTTP、数据库、消息、RPC 属性；属性放置（资源 vs span）。
versioning：语义约定版本管理、稳定性、迁移。适用于语义约定版本迁移。
dash0：Dash0 派生属性及其功能依赖。适用于 Dash0 派生属性。

如何选择正确的属性

先搜索注册表：在 Attribute Registry 中查找概念。如果存在标准名称就使用标准名称（例如优先使用 http.request.method，而不是自定义的 custom.http.verb）。自定义名称会碎片化查询并破坏工具链——只有当注册表中没有条目覆盖该概念时，才创建自定义属性。
检查稳定性：优先使用稳定属性；注意可能变化的实验性属性。参见 versioning。
放在正确的层级：资源属性描述产生遥测的实体；span/log 属性描述单个操作。不要跨层级重复。一旦属性位于某个层级，就在所有服务中一致地保持在该层级。
校验基数：指标属性值必须是低基数（有界集合）。可变数据（用户 ID、带参数的请求路径）应放在 span 属性中，而不是指标属性中。
自定义属性作为最后手段：只有当注册表中没有条目覆盖该概念时，才创建自定义属性。记录该决策并遵循 org.namespace.attribute_name 命名模式。

示例

正确与错误的属性选择

# 正确——使用注册表中的 HTTP 方法属性
span.set_attribute("http.request.method", "GET")

# 错误——为注册表中已有的概念发明自定义属性
span.set_attribute("custom.http.verb", "GET")

资源属性与 span 属性的放置

# 正确——服务身份是资源属性
resource = Resource({"service.name": "checkout-service", "service.version": "2.1.0"})

# 正确——操作特定数据是 span 属性
span.set_attribute("http.request.method", "POST")
span.set_attribute("http.response.status_code", 201)

# 错误——把资源级属性放到每个 span 上
span.set_attribute("service.name", "checkout-service")  # 应放在资源上

指标属性中的基数违规

# 正确——指标属性使用有界、低基数的值
histogram.record(duration_ms, {"http.request.method": "GET", "http.response.status_code": 200})

# 错误——无界值作为指标属性会爆炸式增加存储和查询成本
histogram.record(duration_ms, {"user.id": "u-839201", "url.path": "/orders/839201"})
# 修复：将高基数数值移到 span 属性中
span.set_attribute("user.id", "u-839201")
span.set_attribute("url.path", "/orders/839201")

适用场景

为 HTTP、数据库、消息、RPC 等操作选择或审查遥测属性。
判断属性应放在资源层级还是 span/log 层级。
校验指标属性基数，避免高基数数据进入指标。
进行语义约定版本迁移。
使用 Dash0 派生属性。

限制

本技能不覆盖 span 命名、span 类型和 span 状态码，这些属于 otel-instrumentation 技能。
自定义属性仅在注册表无对应概念时使用，并需记录决策。
具体支持的属性清单以 Attribute Registry 为准。

官方文档

Attribute Registry
Semantic Conventions Specification
Semantic Conventions Repository
Dash0 Semantic Conventions
Dash0 Semantic Conventions Explainer