4. 连接池状态监控：使用 DB.Stats() 方法、理解连接池状态指标

在生产环境中，数据库连接池并非黑盒。Go 标准库 database/sql 提供了 DB.Stats() 方法，返回一个 sql.DBStats 结构体，其中包含了连接池的实时快照。掌握这些指标，是诊断连接泄漏、配置不合理、慢查询堆积的前提。

4.1 sql.DBStats 结构体字段详解

调用 db.Stats() 会返回以下关键字段，每个字段都对应连接池的一个核心状态：

4.2 使用 DB.Stats() 进行实时监控

以下代码展示了如何定期采集连接池状态并输出关键指标：

package main

import (
    "database/sql"
    "fmt"
    "log"
    "time"
)

func monitorPool(db *sql.DB, interval time.Duration) {
    ticker := time.NewTicker(interval)
    defer ticker.Stop()

    for range ticker.C {
        stats := db.Stats()

        // 计算连接池使用率
        var usagePercent float64
        if stats.MaxOpenConnections > 0 {
            usagePercent = float64(stats.InUse) / float64(stats.MaxOpenConnections) * 100
        }

        log.Printf("[连接池状态] Open: %d | InUse: %d | Idle: %d | WaitCount: %d | WaitDuration: %v | 使用率: %.1f%%",
            stats.OpenConnections,
            stats.InUse,
            stats.Idle,
            stats.WaitCount,
            stats.WaitDuration,
            usagePercent,
        )

        // 告警阈值：使用率超过 80% 或出现等待
        if usagePercent > 80 {
            log.Printf("[WARN] 连接池使用率过高: %.1f%%", usagePercent)
        }
        if stats.WaitCount > 0 {
            log.Printf("[WARN] 存在连接等待，累计等待次数: %d", stats.WaitCount)
        }
    }
}

func main() {
    // 假设 db 已经通过 sql.Open 初始化
    var db *sql.DB
    // ... 初始化代码 ...

    go monitorPool(db, 5*time.Second)

    // 业务逻辑...
    select {}
}

4.3 连接池状态流转图

下面的 SVG 图展示了连接在池中的完整生命周期，以及 DB.Stats() 各指标对应的状态节点：

4.4 关键指标解读与异常场景

理解指标的正常范围比单纯采集更重要。以下表格总结了常见异常模式及其根因：

4.5 集成到 Prometheus 指标暴露

在生产环境中，手动打印日志不够高效。以下代码展示了如何将 DB.Stats() 转换为 Prometheus Gauge 指标：

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

var (
    dbOpenConnections = promauto.NewGauge(prometheus.GaugeOpts{
        Name: "db_open_connections",
        Help: "当前打开的数据库连接数",
    })
    dbInUseConnections = promauto.NewGauge(prometheus.GaugeOpts{
        Name: "db_in_use_connections",
        Help: "当前正在使用的数据库连接数",
    })
    dbIdleConnections = promauto.NewGauge(prometheus.GaugeOpts{
        Name: "db_idle_connections",
        Help: "当前空闲的数据库连接数",
    })
    dbWaitCount = promauto.NewCounter(prometheus.CounterOpts{
        Name: "db_wait_count_total",
        Help: "累计等待连接次数",
    })
)

func recordDBStats(db *sql.DB) {
    stats := db.Stats()
    dbOpenConnections.Set(float64(stats.OpenConnections))
    dbInUseConnections.Set(float64(stats.InUse))
    dbIdleConnections.Set(float64(stats.Idle))
    dbWaitCount.Add(float64(stats.WaitCount))
}

4.6 监控指标与连接池配置的联动关系

下面的 SVG 图展示了监控指标如何反向指导连接池参数调整，形成闭环优化：

4.7 实战：快速定位连接池瓶颈

1. 第一步：在业务低峰期记录基线指标，包括 OpenConnections、InUse、Idle 的均值与峰值。
2. 第二步：设置告警规则：当 InUse / MaxOpenConns > 0.8 或 WaitCount 在 1 分钟内增长超过 10 次时触发告警。
3. 第三步：告警触发后，检查 InUse 是否持续不降——如果是，优先排查连接泄漏；如果波动大，优先排查慢查询。
4. 第四步：使用 SHOW PROCESSLIST 或 pg_stat_activity 确认数据库端连接状态，与 DB.Stats() 数据交叉验证。
5. 第五步：根据分析结果调整连接池参数，调整后持续监控至少 30 分钟，确认指标回归正常范围。