选择、放置与校验 OpenTelemetry…

在为遥测数据选择、应用或审查属性与指标时，按 OpenTelemetry 语义约定规范正确选名、定级、控基数并处理版本迁移。

适用场景

解决思路

1. 先在 Attribute Registry 中查找概念：若已有标准名称就使用标准名（例如优先用 `http.request.method` 而不是自定义的 `custom.http.verb`），因为自定义名称会割裂查询并破坏工具链，只有在注册表中没有覆盖该概念时才创建自定义属性。
2. 检查属性的稳定性：优先使用 `stable` 属性，并留意可能变化的 `experimental` 属性，参考 versioning 规则。
3. 把属性放在正确的层级：resource 属性描述产生遥测的实体，span/log 属性描述单次操作；不要跨层级重复，且一旦某属性放在某层级，就在所有服务中保持一致。
4. 校验基数：metric 属性值必须是低基数（有界集合）；可变数据（用户 ID、带参数的请求路径）应放在 span 属性中，而不是 metric 属性中。
5. 把自定义属性作为最后手段：只有在注册表没有覆盖该概念时才创建自定义属性，记录该决定并遵循 `org.namespace.attribute_name` 命名模式。
6. 按官方文档与规则文件执行：参考 Attribute Registry、Semantic Conventions Specification、Semantic Conventions Repository、Dash0 Semantic Conventions 及 rules/attributes.md、rules/versioning.md、rules/dash0.md。
7. span 命名、span kind 和 span status code 相关事项改用 otel-instrumentation 技能处理。
8. 正确示例：`span.set_attribute("http.request.method", "GET")`；错误示例：`span.set_attribute("custom.http.verb", "GET")`。
9. 资源与 span 放置示例：`resource = Resource({"service.name": "checkout-service", "service.version": "2.1.0"})` 放在 resource；`span.set_attribute("http.request.method", "POST")`、`span.set_attribute("http.response.status_code", 201)` 放在 span；不要把 `service.name` 放到每个 span 上。
10. 基数违规示例：正确做法是 `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")`。

适用边界 · 注意事项

• 需要处理 span 名称、span kind 或 span status code 时，应改用 otel-instrumentation 技能。
• 概念已在 Attribute Registry 中有标准条目时，不要创建自定义属性。
• 不要把高基数或可变数据用作 metric 属性，也不要把 resource 级属性重复放到每个 span 上。