4. 连接池状态监控：Stats() 方法、连接池状态指标解读

在生产环境中，连接池并非黑盒。Go 标准库 database/sql 包为 *sql.DB 提供了 Stats() 方法，返回一个 sql.DBStats 结构体，其中包含了连接池的实时快照。理解这些指标是进行连接池调优的前提——没有度量，就没有优化。

4.1 Stats() 方法：获取连接池快照

Stats() 是线程安全的，可以在任意 goroutine 中调用，返回当前连接池的瞬时状态。其返回结构体定义如下：

type DBStats struct {
    MaxOpenConnections int           // 最大打开连接数（配置值）
    OpenConnections    int           // 当前已建立的连接数（含空闲与使用中）
    InUse              int           // 当前正在被使用的连接数
    Idle               int           // 当前空闲的连接数
    WaitCount          int64         // 等待获取连接的累计次数
    WaitDuration       time.Duration // 等待获取连接的累计总耗时
    MaxIdleClosed      int64         // 因超过 MaxIdleConns 而关闭的连接累计数
    MaxIdleTimeClosed  int64         // 因超过 ConnMaxIdleTime 而关闭的连接累计数
    MaxLifetimeClosed  int64         // 因超过 ConnMaxLifetime 而关闭的连接累计数
}

4.2 核心指标解读

以下表格对关键指标进行逐一解读，并给出健康区间参考：

4.3 连接池状态流转图

下面的 SVG 图展示了连接从创建到关闭的完整状态机，以及各指标对应的状态节点：

4.4 指标联动分析：典型场景

单一指标往往无法说明问题，需要组合分析。以下列出三种典型异常场景及其指标特征：

4.5 监控代码示例

以下是一个将 Stats() 集成到 Prometheus 指标采集的典型实现：

import (
    "database/sql"
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promauto"
)

type DBMonitor struct {
    db *sql.DB

    openConns   prometheus.Gauge
    inUseConns  prometheus.Gauge
    idleConns   prometheus.Gauge
    waitCount   prometheus.Counter
    waitDurMs   prometheus.Counter
}

func NewDBMonitor(db *sql.DB, subsystem string) *DBMonitor {
    return &DBMonitor{
        db: db,
        openConns: promauto.NewGauge(prometheus.GaugeOpts{
            Subsystem: subsystem, Name: "open_connections",
            Help: "当前打开的连接数",
        }),
        inUseConns: promauto.NewGauge(prometheus.GaugeOpts{
            Subsystem: subsystem, Name: "in_use_connections",
            Help: "当前正在使用的连接数",
        }),
        idleConns: promauto.NewGauge(prometheus.GaugeOpts{
            Subsystem: subsystem, Name: "idle_connections",
            Help: "当前空闲连接数",
        }),
        waitCount: promauto.NewCounter(prometheus.CounterOpts{
            Subsystem: subsystem, Name: "wait_count_total",
            Help: "等待获取连接的累计次数",
        }),
        waitDurMs: promauto.NewCounter(prometheus.CounterOpts{
            Subsystem: subsystem, Name: "wait_duration_milliseconds_total",
            Help: "等待获取连接的累计毫秒数",
        }),
    }
}

// Collect 定期采集指标，建议在独立的 goroutine 中每 10s 调用一次
func (m *DBMonitor) Collect() {
    stats := m.db.Stats()
    m.openConns.Set(float64(stats.OpenConnections))
    m.inUseConns.Set(float64(stats.InUse))
    m.idleConns.Set(float64(stats.Idle))
    m.waitCount.Add(float64(stats.WaitCount - m.lastWaitCount))
    m.waitDurMs.Add(float64(stats.WaitDuration.Milliseconds() - m.lastWaitDurMs))
    m.lastWaitCount = stats.WaitCount
    m.lastWaitDurMs = stats.WaitDuration.Milliseconds()
}

4.6 健康阈值速查表

以下表格可作为日常巡检的参考标准：