3. Prometheus 监控基础回顾：指标类型、PromQL 与告警规则

在深入 API 弃用迁移与 Prometheus 监控联动升级之前，必须夯实 Prometheus 监控基础。本章将系统回顾 Prometheus 的四大核心指标类型、PromQL 查询语言的核心语法以及告警规则的编写范式，为后续章节的实战操作提供理论支撑。

3.1 四大核心指标类型

Prometheus 的指标模型基于时间序列，每个时间序列由指标名称和一组标签唯一标识。根据数据语义和计算方式，指标分为四种类型：Counter、Gauge、Histogram 和 Summary。理解它们的差异是设计监控方案的前提。

3.2 PromQL 基础：查询与聚合

PromQL（Prometheus Query Language）是 Prometheus 的查询语言，支持即时查询和范围查询。掌握 PromQL 是编写告警规则和构建仪表盘的基础。

3.2.1 选择器与匹配模式

• 精确匹配：http_requests_total{method="GET", handler="/api/v1/deprecated"}
• 正则匹配：http_requests_total{handler=~"/api/v[12]/.*"}
• 负向匹配：http_requests_total{handler!~"/api/v2/.*"}

3.2.2 常用函数与操作符

3.2.3 典型查询示例

# 查询弃用 API 的 QPS（每秒请求数）
rate(http_requests_total{handler="/api/v1/deprecated"}[5m])

# 查询弃用 API 的错误率（错误请求 / 总请求）
sum(rate(http_requests_total{handler="/api/v1/deprecated", status=~"5.."}[5m]))
/
sum(rate(http_requests_total{handler="/api/v1/deprecated"}[5m]))

# 查询新 API 的 P99 延迟（基于 Histogram）
histogram_quantile(0.99,
  sum(rate(http_request_duration_seconds_bucket{handler="/api/v2/new"}[5m])) by (le)
)

3.3 告警规则：从指标到通知

告警规则是 Prometheus 监控体系的核心输出。通过 PromQL 表达式定义告警条件，Prometheus 会持续评估规则，并在满足条件时触发告警。告警规则通常定义在 rules.yml 文件中，并通过 rule_files 配置加载。

3.3.1 告警规则结构

groups:
  - name: api_deprecation_alerts
    rules:
      - alert: HighDeprecatedAPIErrorRate
        expr: |
          sum(rate(http_requests_total{handler="/api/v1/deprecated", status=~"5.."}[5m]))
          /
          sum(rate(http_requests_total{handler="/api/v1/deprecated"}[5m])) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "弃用 API 错误率过高（当前值：{{ $value | humanizePercentage }}）"
          description: "弃用 API /api/v1/deprecated 的 5xx 错误率已超过 5%，持续 5 分钟。请立即检查后端服务状态。"

3.3.2 规则关键字段说明

3.3.3 告警规则设计原则

• 避免空泛告警：每个告警规则必须有明确的业务含义和可操作的动作。例如“弃用 API 错误率 > 5%”比“错误率过高”更有价值。
• 合理设置 for 持续时间：对于瞬时故障（如网络抖动），设置 for: 1m 或 5m；对于资源耗尽类问题，可以设置 for: 0 立即触发。
• 使用模板变量：在 annotations 中使用 {{ $value }}、{{ $labels.instance }} 等变量，让告警信息更具体。
• 分级告警：通过 labels.severity 区分告警级别（critical / warning / info），便于告警接收方区分优先级。

3.4 指标类型与 PromQL 联动：可视化与告警

理解指标类型与 PromQL 的联动关系，是构建高效监控体系的关键。下面的 SVG 图展示了从指标采集到告警触发的完整链路。

3.5 实战：为 API 弃用迁移设计监控指标

结合本章的知识点，我们为 API 弃用迁移场景设计一套完整的监控指标和告警规则。下面的 SVG 图展示了指标设计的分层架构。