📚 课程目录第4章 API元数据标注

4. Prometheus 基础回顾：指标类型与 PromQL 入门

在构建 API 弃用检测与告警体系之前，必须牢固掌握 Prometheus 的核心数据模型与查询语言。本章将系统回顾 Prometheus 的四种主要指标类型、数据模型结构以及 PromQL 基础查询语法，为后续编写弃用检测规则和告警表达式打下坚实基础。

4.1 Prometheus 数据模型

Prometheus 将所有采集到的数据存储为时间序列（Time Series）。每个时间序列由指标名称（Metric Name）和一组标签（Labels）唯一标识。

组件	说明	示例
指标名称	描述被监控对象的语义，通常包含命名空间	`api_deprecation_requests_total`
标签	键值对，用于维度区分，支持多维度聚合	`{endpoint="/v1/users", method="GET", version="v1"}`
样本值	一个 float64 数值，代表某个时刻的测量值	`1024.5`
时间戳	毫秒精度的时间点	`1710000000000`

  关键概念： 标签是 Prometheus 数据模型的灵魂。通过标签，你可以将同一个指标按不同维度（如 API 版本、HTTP 方法、状态码）进行切片和聚合，这是实现 API 弃用检测多维度分析的基础。

4.2 四种核心指标类型

Prometheus 客户端库提供了四种指标类型，每种类型适用于不同的监控场景。理解它们的差异是编写正确 PromQL 查询的前提。

指标类型	核心特征	典型用途	API 弃用场景
Counter	只增不减（除重启外），累计计数	请求总数、错误总数、任务完成数	统计弃用 API 的累计调用次数
Gauge	可增可减，反映当前状态	内存使用率、并发连接数、队列深度	当前正在使用弃用 API 的客户端数量
Histogram	对观测值进行分桶统计，提供分布信息	请求延迟分布、响应大小分布	弃用 API 的响应延迟分布，识别性能退化
Summary	类似 Histogram，但直接计算分位数	请求延迟的 p50/p90/p99	弃用 API 的延迟分位数监控

常见误区： Counter 类型不能直接用于计算当前速率，必须配合 rate() 或 irate() 函数使用。直接对 Counter 进行聚合会得到累计值，而非实时流量。

4.3 指标类型与 PromQL 操作对照

不同的指标类型在 PromQL 中有不同的推荐操作方式。下表总结了常用操作及其适用类型：

PromQL 操作	适用类型	说明	示例
`rate()`	Counter	计算每秒平均增长率	`rate(api_deprecation_requests_total[5m])`
`increase()`	Counter	计算时间范围内的增量	`increase(api_deprecation_errors_total[1h])`
`avg_over_time()`	Gauge	计算时间范围内的平均值	`avg_over_time(api_deprecation_active_clients[5m])`
`histogram_quantile()`	Histogram	从直方图计算分位数	`histogram_quantile(0.95, ...)`
`sum() / by()`	所有类型	按标签维度聚合	`sum by(version) (rate(...))`

4.4 PromQL 入门：选择器与聚合

PromQL 是 Prometheus 的查询语言，核心操作包括即时查询和范围查询。

4.4.1 指标选择器

# 精确匹配
api_deprecation_requests_total{version="v1", method="GET"}

# 正则匹配（匹配 v1, v2, v3）
api_deprecation_requests_total{version=~"v[1-3]"}

# 负向匹配（排除 v1）
api_deprecation_requests_total{version!="v1"}

# 匹配所有标签
{__name__=~"api_deprecation_.*"}

4.4.2 常用聚合操作

# 按版本聚合请求速率
sum by(version) (rate(api_deprecation_requests_total[5m]))

# 按端点和版本聚合错误率
sum by(endpoint, version) (rate(api_deprecation_errors_total[5m]))

# 计算弃用 API 占总请求的比例
sum(rate(api_deprecation_requests_total[5m])) / sum(rate(api_requests_total[5m])) * 100

实战技巧： 在 API 弃用检测中，sum by(version) 是最常用的聚合模式。通过按 API 版本分组，你可以快速识别哪个版本的弃用 API 流量最高，从而确定优先治理目标。

4.5 指标类型与数据模型关系图

下图展示了 Prometheus 数据模型、指标类型与 PromQL 操作之间的整体关系：

4.6 实战：为 API 弃用检测选择正确的指标类型

在 API 弃用检测场景中，不同监控需求对应不同的指标类型选择：

弃用 API 调用总量 → Counter：使用 api_deprecation_requests_total，配合 rate() 计算每秒调用速率。
当前使用弃用 API 的客户端数 → Gauge：使用 api_deprecation_active_clients，反映实时活跃情况。
弃用 API 响应延迟分布 → Histogram：使用 api_deprecation_request_duration_seconds，通过 histogram_quantile() 计算 p95/p99。
弃用 API 错误率 → Counter：使用 api_deprecation_errors_total，按状态码标签细分。

  最佳实践： 在定义 API 弃用指标时，建议统一使用 api_deprecation_ 作为指标名称前缀，并包含 version、endpoint、method 等核心标签。这样在 PromQL 查询时可以通过 {__name__=~"api_deprecation_.*"} 快速筛选所有弃用相关指标。

4.7 指标类型选择决策流程

当你在设计 API 弃用监控指标时，可以按照以下决策流程选择正确的指标类型：

决策示例： 如果你需要监控“弃用 API 的请求速率”，这是累计值 → 选择 Counter；如果你需要监控“当前有多少客户端正在调用弃用 API”，这是当前值 → 选择 Gauge；如果你需要分析“弃用 API 的延迟分布”，则需要 Histogram。

4.8 本章小结

Prometheus 数据模型由指标名称 + 标签唯一标识一个时间序列，标签是实现多维度聚合的关键。
四种指标类型各有适用场景：Counter 用于累计计数，Gauge 用于当前状态，Histogram 和 Summary 用于分布分析。
PromQL 选择器支持精确匹配、正则匹配和负向匹配，rate()、sum by() 是 API 弃用检测中最常用的函数。
在定义 API 弃用指标时，建议统一命名规范并包含 version、endpoint 等核心标签，便于后续聚合查询。