Metric Design 基础：定义、类型与命名规范

在可观测性体系中，Metric（度量指标）是质量门禁卡点的最小数据单元。它是一组带时间戳的数值序列，用于描述系统在某一时刻或某一时间窗口内的状态、行为或性能。只有正确理解 Metric 的本质、分类与命名规则，才能设计出可被门禁卡点准确评估的告警阈值基线。

2.1 什么是 Metric

Metric 是对系统特征进行数值化抽象的结果，通常由以下三要素构成：

2.2 Metric 的四种核心类型

不同场景需要不同语义的 Metric 类型。以下是生产环境中最常见的四种类型及其适用场景：

2.3 Metric 命名规范

统一的命名规范是团队协作和自动化门禁解析的基础。推荐遵循 Prometheus 命名规范，该规范已被业界广泛采纳：

• 基础格式：<namespace>_<subsystem>_<metric_name>[_<unit>]
• 命名规则：
  • 全部使用小写字母 + 下划线（snake_case）
  • Metric Name 必须以字母开头
  • 使用 _total 后缀标识 Counter 类型
  • 使用 _seconds / _bytes / _count 等后缀标识单位
  • Histogram 自动生成 _bucket、_count、_sum 后缀

2.4 Metric 类型与命名规范关系图

下图展示了四种 Metric 类型在质量门禁卡点中的典型数据流，以及命名规范如何贯穿始终：

2.5 代码示例：Prometheus Client 定义规范 Metric

以下 Go 代码展示了如何按照规范定义四种类型的 Metric，并注入质量门禁所需的标签：

// Counter：请求总数，带 method 和 status 标签
apiRequestTotal = prometheus.NewCounterVec(
    prometheus.CounterOpts{
        Name: "api_http_requests_total",
        Help: "Total number of HTTP requests.",
    },
    []string{"method", "status"},
)

// Gauge：当前活跃连接数
activeConnections = prometheus.NewGauge(
    prometheus.GaugeOpts{
        Name: "api_active_connections",
        Help: "Current number of active connections.",
    },
)

// Histogram：请求延迟，单位秒，分桶 0.1~10
requestDuration = prometheus.NewHistogramVec(
    prometheus.HistogramOpts{
        Name:    "api_request_duration_seconds",
        Help:    "Request latency in seconds.",
        Buckets: []float64{0.1, 0.3, 0.5, 1, 3, 5, 10},
    },
    []string{"method"},
)

// Summary：延迟分位数，客户端预计算
requestLatencySummary = prometheus.NewSummaryVec(
    prometheus.SummaryOpts{
        Name:       "api_request_latency_seconds",
        Help:       "Request latency summary.",
        Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
    },
    []string{"method"},
)