2、指标口径设计原则：明确业务语义、避免指标爆炸、命名规范

指标口径（Metric Instrumentation）是自定义指标体系的骨架。口径设计一旦偏离业务语义或缺乏约束，轻则导致数据解读歧义，重则引发指标爆炸、存储成本失控。本节从三个核心原则展开：业务语义明确、避免指标爆炸、命名规范，并给出 OpenTelemetry 的最佳实践对照。

2.1 原则一：明确业务语义

每个指标必须能回答三个问题：测量什么（What）、在什么维度上（Where）、代表什么业务含义（Why）。

2.2 原则二：避免指标爆炸

指标爆炸通常由高基数标签（High Cardinality Labels）引发。例如将 user_id、request_id、session_id 直接作为标签，会导致时间序列数量呈指数级增长。

下表列出常见的高基数来源与应对策略：

2.3 原则三：命名规范（OTel 命名规范与最佳实践）

OpenTelemetry 在 Semantic Conventions 中定义了指标命名规范，核心规则如下：

• 命名空间前缀：使用 namespace. 开头，例如 http.server.、db.client.、messaging.。
• 小写字母 + 下划线：禁止使用大写字母、驼峰、连字符。例如 request_duration 而非 requestDuration 或 request-duration。
• 单位后缀：如果指标有明确单位，在名称末尾添加 _seconds、_bytes、_total 等后缀。例如 http.server.request_duration_seconds。
• 避免冗余：不要在名称中重复命名空间。例如 http.server.http_request_count 中的 http 重复，应改为 http.server.request_count。
• 标签名使用点分隔：例如 http.method、http.status_code，保持与 Semantic Conventions 一致。

以下是一个符合 OTel 规范的指标定义示例：

// 符合 OTel 规范的指标定义
metric_name: "http.server.request_duration_seconds"
metric_type: Histogram
unit: "seconds"
description: "HTTP 服务端请求处理耗时，按路由和方法区分"
attributes:
  - name: "http.method"
    type: string
    description: "HTTP 请求方法，如 GET、POST"
  - name: "http.route"
    type: string
    description: "路由模板，如 /api/users/:id"
  - name: "http.status_code"
    type: int
    description: "HTTP 响应状态码，如 200、404"

2.4 口径设计流程总览

下图展示了从业务需求到指标埋点的完整设计流程，帮助你在实际项目中落地上述原则：

2.5 常见口径设计反模式

• “万能指标”反模式：用一个指标携带所有标签，试图覆盖所有查询场景。结果导致基数爆炸，查询性能急剧下降。
• “标签即字段”反模式：将数据库字段直接映射为标签，不考虑基数与业务相关性。例如将 product_sku（百万级）直接作为标签。
• “命名随意”反模式：团队内不同成员使用不同命名风格，如 req_count、requestCount、request-count，导致指标无法统一查询。
• “无单位”反模式：指标名称不包含单位，使用者需要猜测是毫秒还是秒，是字节还是千字节。