3. 连接池核心指标设计：活跃连接数、空闲连接数、等待队列长度、连接超时次数

连接池是后端服务与数据库、缓存、消息队列等下游资源之间的关键桥梁。水位巡检的核心在于通过 Prometheus 指标实时感知连接池的内部状态，从而在资源耗尽前触发告警或自动伸缩。本章聚焦四个最核心的指标：活跃连接数、空闲连接数、等待队列长度、连接超时次数，并给出对应的 Prometheus 指标配置与巡检阈值建议。

3.1 四类核心指标的定义与业务含义

下表从指标名称、Prometheus 类型、典型来源、业务含义四个维度进行对比，帮助你在巡检面板中快速定位每个指标的作用。

3.2 指标间的联动关系与水位模型

四个指标并非孤立存在，它们共同构成连接池的“水位模型”。下图展示了从请求到达、获取连接到超时失败的全链路指标流转关系。

3.3 Prometheus 指标配置与告警规则

以下给出基于 HikariCP 连接池的 Prometheus 指标采集配置示例，以及对应的告警规则。实际部署时请根据连接池类型（Druid、Tomcat JDBC、Lettuce 等）调整 metric 名称。

3.3.1 指标采集配置（prometheus.yml）

# 通过 JMX Exporter 或 Micrometer 暴露的 HikariCP 指标
scrape_configs:
  - job_name: 'hikaricp'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['localhost:8080']
    # 确保以下指标被采集
    # hikaricp_connections_active
    # hikaricp_connections_idle
    # hikaricp_connections_pending
    # hikaricp_connections_timeout_total

3.3.2 告警规则（prometheus-rules.yml）

groups:
  - name: connection_pool_alerts
    rules:
      # 高水位预警：活跃连接数超过最大连接数的 80%
      - alert: ConnectionPoolHighWatermark
        expr: |
          hikaricp_connections_active / 
          (hikaricp_connections_active + hikaricp_connections_idle 
           + on(instance) group_left hikaricp_connections_max) 
          > 0.8
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "连接池高水位 (instance {{ $labels.instance }})"
          description: "活跃连接占比超过 80%，当前值: {{ $value | humanizePercentage }}"

      # 等待队列告警：等待队列长度持续大于 0
      - alert: ConnectionPoolQueueBuilding
        expr: hikaricp_connections_pending > 0
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: "连接池等待队列非空 (instance {{ $labels.instance }})"
          description: "等待队列长度: {{ $value }}，连接供给可能不足"

      # 连接超时告警：5 分钟内超时次数增长超过 5 次
      - alert: ConnectionPoolTimeoutSpike
        expr: |
          rate(hikaricp_connections_timeout_total[5m]) > 0.0167
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "连接超时次数激增 (instance {{ $labels.instance }})"
          description: "5 分钟超时速率: {{ $value | humanize }} 次/秒"

3.4 指标可视化与巡检面板设计

在 Grafana 中，建议将四个核心指标组织在一个面板行中，形成“连接池水位总览”。下表给出每个面板的推荐图表类型和 Y 轴单位。

同时，建议在面板上方添加一个“连接池水位状态”的 Singlestat 或 Stat 面板，通过公式 (active / max) * 100 实时显示当前水位百分比，并设置颜色阈值：绿色（0-60%）、黄色（60-80%）、红色（80-100%）。

3.5 典型巡检场景与应对策略

以下列表总结了四种常见的水位异常场景及其根因分析方向，帮助你快速定位问题。

• 场景一：活跃连接数持续高位，空闲连接数接近 0
  • 可能原因：业务流量突增、慢查询导致连接占用时间过长、连接泄漏。
  • 应对策略：检查慢 SQL、增加 maxPoolSize、排查未关闭的 Connection 对象。
• 场景二：等待队列长度持续增长，但活跃连接数未达上限
  • 可能原因：连接获取锁竞争激烈、数据库端连接数限制、网络延迟。
  • 应对策略：检查数据库 max_connections、优化连接获取超时时间、考虑连接池拆分。
• 场景三：连接超时次数突然飙升
  • 可能原因：数据库宕机或重启、连接池配置的 connectionTimeout 过短、后端负载过高。
  • 应对策略：确认数据库健康状态、适当延长 connectionTimeout、增加连接池或限流。
• 场景四：空闲连接数过高，但活跃连接数很低
  • 可能原因：连接池初始化连接数过多、业务低峰期、连接未及时回收。
  • 应对策略：调整 minimumIdle 参数、启用连接空闲超时回收（idleTimeout）。