3. 指标名称与标签的语义约定：Semantic Conventions
在 OpenTelemetry 生态中，Semantic Conventions（语义约定） 是一套官方定义的命名规范，用于统一指标（Metric）和标签（Attribute/Label）的命名方式。遵循这套规范，可以确保不同组件、不同语言 SDK 上报的数据具有一致的语义，从而避免“同名不同义”或“同义不同名”的混乱。
核心原则： 语义约定的目标是让指标名称和标签名称具备“自描述”能力——任何人看到名称，就能准确理解其度量对象、单位、方向以及上下文。
3.1 指标命名规则
OpenTelemetry 的指标名称遵循 点分命名空间（Dot-Separated Namespace） 结构，从通用到具体逐级细化。命名规则可归纳为以下要点：
| 规则维度 | 规范要求 | 正确示例 | 错误示例 |
|---|---|---|---|
| 命名空间前缀 | 使用 metric. 或组件名（如 http.、db.）开头 |
http.server.request.duration |
request_duration（缺少上下文） |
| 单位后缀 | 基础单位（秒、字节、个）不强制加后缀；非基础单位需明确标注 | system.cpu.time（秒）system.network.packets（个） |
system.cpu.time.seconds（冗余） |
| 词序 | 从通用到具体：领域.子系统.度量.单位 |
db.client.connections.usage |
connections.db.client.usage（顺序混乱） |
| 分隔符 | 仅使用 .（点）作为层级分隔，_（下划线）用于单词连接 |
http.server.active_requests |
http-server-active-requests（使用连字符） |
| 大小写 | 全部小写，禁止驼峰或大写 | rpc.client.duration |
RPC.Client.Duration |
命名模板公式：
例如：
<domain>.<subsystem>.<measurement>[.<unit>]例如：
http.server.request.body.size（HTTP 服务器请求体大小，单位字节）
3.2 标签（Attribute）命名规范
标签用于描述指标的维度信息，如请求方法、状态码、服务名称等。OpenTelemetry 对标签名称也有严格的语义约定：
- 命名风格： 全部小写，单词间使用下划线（
_）连接，禁止点号或驼峰。 - 命名空间： 通用标签（如
service.name）使用点号分隔命名空间；技术特定标签（如http.method）使用组件前缀。 - 语义明确： 标签名称必须能清晰表达其值的含义，避免缩写歧义。
- 类型一致： 同一标签名在不同指标中必须保持相同的数据类型（字符串、整数、布尔等）。
| 标签类别 | 规范示例 | 说明 |
|---|---|---|
| 资源标签 | service.name、deployment.environment |
标识服务身份与部署环境 |
| HTTP 标签 | http.method、http.status_code、http.url |
描述 HTTP 请求/响应的属性 |
| 数据库标签 | db.system、db.operation、db.sql.table |
描述数据库操作上下文 |
| 网络标签 | net.host.name、net.sock.peer.addr |
描述网络连接端点 |
| 自定义标签 | custom.business_tier、custom.region |
建议使用 custom. 前缀避免冲突 |
避坑提示： 不要将动态值（如用户 ID、请求 ID）直接作为标签名称的一部分。标签名应是固定的维度键，值才是动态的。例如：
http.method 是标签名，GET 是标签值。
3.3 指标与标签的语义关系
指标名称定义“度量什么”，标签定义“从哪些维度看这个度量”。两者共同构成一个完整的可观测性数据点。以下 SVG 图展示了这种层级关系：
3.4 常见指标命名对照表
以下表格列出 OpenTelemetry Semantic Conventions 中定义的常见指标及其命名规范，供你在重命名或合并时参考：
| 领域 | 指标名称 | 指标类型 | 单位 | 关键标签 |
|---|---|---|---|---|
| HTTP 服务端 | http.server.request.duration |
Histogram | 秒 (s) | http.method, http.status_code, http.route |
| HTTP 客户端 | http.client.request.duration |
Histogram | 秒 (s) | http.method, http.status_code, server.address |
| 数据库 | db.client.connections.usage |
UpDownCounter | 个 | db.system, db.connection.state |
| 消息队列 | messaging.receive.duration |
Histogram | 秒 (s) | messaging.system, messaging.destination.name |
| 系统 CPU | system.cpu.time |
Counter | 秒 (s) | cpu.state (idle, user, system) |
| 系统内存 | system.memory.usage |
UpDownCounter | 字节 (By) | memory.type (used, free, cached) |
| RPC 服务端 | rpc.server.duration |
Histogram | 秒 (s) | rpc.system, rpc.service, rpc.method |
3.5 标签合并时的语义冲突处理
在指标重命名与标签合并过程中，最常见的风险是 语义冲突——两个来源的标签名称相同但含义不同，或含义相同但名称不同。以下流程总结了处理策略：
3.6 实践建议与检查清单
指标重命名检查清单：
- ✅ 指标名称是否以标准域名空间开头（
http.、db.、system.等）？ - ✅ 是否遵循“域名.子系统.度量.单位”的从通用到具体顺序？
- ✅ 标签名称是否全部小写并使用下划线分隔？
- ✅ 是否存在同名标签但语义不一致的情况？
- ✅ 自定义标签是否添加了
custom.前缀以避免与标准标签冲突？ - ✅ 标签值的数据类型是否在相同标签名下保持一致？
- ✅ 是否已移除标签名称中的动态值（如用户 ID、会话 ID）？
推荐工具： 使用 OpenTelemetry 官方提供的 Semantic Conventions 验证器（本地 CLI 或 CI 集成）自动检查指标和标签命名是否符合规范。在重命名脚本中集成该验证器，可以在合并前拦截大部分命名违规。