otel-name-metric

用途

该技能用于审查或创建符合 OpenTelemetry（OTel）语义约定的指标名称，确保命名格式、仪器选择、单位放置与属性分离均正确。应用任何规则前，需先获取最新命名指南以检查更新：

• https://opentelemetry.io/docs/specs/semconv/general/naming/
• https://opentelemetry.io/docs/specs/semconv/general/metrics/
• https://opentelemetry.io/blog/2025/how-to-name-your-metrics/

若获取内容与技能中的规则冲突，应遵循获取内容并标记差异。

核心原则

指标名称标识“测量什么”。其他信息——谁在测量、在哪里运行、哪个版本——应放入属性或资源属性。

指标名称模式

OTel 规范定义以下模式：

• 默认模式：{area}.{metric_name}。当 area 或 metric_name 已隐含通信侧时使用。示例：system.memory.usage、kestrel.connection.duration、messaging.process.duration。
• 客户端/服务器模式：{area}.{client|server}.{metric_name}。当通信侧对给定 area 和 metric_name 不明确时使用。两侧视角都存在时包含 client 或 server（如 http.server.* 与 http.client.*）；系统名隐含侧时省略（如 kestrel 始终是服务器）；指标名隐含侧时省略（如 messaging.process 始终是消费者）。示例：http.server.request.duration、db.client.operation.duration。
• 系统专属模式：{system_name}.*.{metric_name}。当指标特定于某系统、项目或提供商时使用。示例：azure.cosmosdb.client.operation.request_charge、jvm.gc.duration。

段的工作方式

指标名称使用点分隔命名空间，每个点增加特异性。命名空间可嵌套，段数不固定。实际指标从 2 段（system.uptime）到 6 段（azure.cosmosdb.client.operation.request_charge）不等。遵循 {object}.{property} 原则，保持精确：使用 system.network.packet.dropped 而非 system.network.dropped。

名称与属性

• 若维度改变“测量什么”→ 放入指标名称。
• 若改变“谁/哪里/何时”→ 放入属性。

维度	放入	原因
协议域（http、db）	名称	改变测量内容
通信侧（client、server）	名称（不明确时）	改变视角
实体与属性（request.duration）	名称	改变捕获内容
服务名	资源属性	同一指标跨服务
环境	资源属性	同一指标跨环境
版本	资源属性	同一指标跨版本
HTTP 方法、路由	指标属性	同一指标内过滤
技术栈	名称中不出现	无法在语言迁移中保留
单位（ms、bytes）	单位元数据字段	UCUM 标准，不放入名称

命名格式

• 小写，点分隔命名空间。
• 段内 snake_case：http.response.status_code。
• 必须以字母开头，以字母数字结尾。
• 无连续分隔符（..、__、._）。
• 仅可打印基本拉丁字符（U+0021–U+007E）。

测量后缀

后缀	含义	示例
entity.limit	已知总量	system.memory.limit
entity.usage	已知总量中的已用量	system.memory.usage
entity.utilization	使用量/限制的比例（0–1）	system.memory.utilization
entity.time	时间流逝	system.cpu.time
entity.io	双向数据流	system.network.io

复数规则

• 离散可计数实例的 Counter 用复数：system.paging.faults、system.disk.operations。
• utilization、duration、time 不用复数：system.filesystem.utilization。
• UpDownCounter 名称不应复数：system.process.count 而非 system.processes。
• 绝不追加 _total——在 delta 后端中会混淆含义。

单位约定（UCUM）

• 单位放入元数据，不放入指标名称。
• 使用无前缀单位：By 而非 MiBy。
• 时长：使用秒（s）。
• 利用率：无量纲，单位 1。
• 花括号注解匹配语法数：{request} 而非 {requests}。
• 区分大小写：Cel 表示摄氏度。

属性命名

• 模式：{object}.{property}，点分隔。
• 小写，段内 snake_case。
• 相关属性归入同一命名空间：order.id、order.total、order.status。
• 保持名称稳定；让值承载动态数据。
• 不要将用户 ID、请求 ID 或 IP 地址作为指标属性——会导致基数爆炸。

参考资料

references/ 目录包含特定主题的详细指南，任务需要更深上下文时阅读：

• namespaces.md——官方命名空间根完整目录、展示每个指标使用哪种模式的示例、自定义命名空间指南。
• instruments.md——仪器选择决策树、可加性规则、同步与异步、UpDownCounter 一致性。
• anti-patterns.md——坏→好命名示例、属性反模式、基数陷阱。

审查清单

审查指标定义时验证：

• 名称使用点分隔小写 snake_case。
• 指标名称中无单位、服务名、环境或版本。
• 测量使用正确的仪器类型。
• 单位在元数据字段中，遵循 UCUM。
• 复数与仪器类型匹配。
• 无 _total 后缀。
• 自定义名称不与 otel.* 或现有语义约定命名空间冲突。
• 属性遵循 {object}.{property} 格式。
• 指标属性中无高基数数值。
• UpDownCounter 增减使用匹配的属性值。

输出

提供：

• 已审查指标列表，附每项清单的通过/失败。
• 任何违规的建议修正。
• 缺失或错误时的仪器类型建议。
• 属性放置修正（名称 → 资源 → 指标属性）。