4. 连接池状态监控：使用 DB.Stats() 获取连接池运行指标

连接池是一个动态运行的资源池，其内部状态随着并发请求、网络延迟、数据库负载实时变化。如果不监控连接池的运行指标，就无法判断当前配置是否合理，也无法在慢查询或连接泄漏发生时快速定位问题。Go 标准库 database/sql 提供了 DB.Stats() 方法，返回一个 sql.DBStats 结构体，包含了连接池的完整运行快照。

4.1 sql.DBStats 核心字段解析

每次调用 db.Stats() 都会返回当前时刻的原子快照。下表列出了最关键的字段及其业务含义：

4.2 连接池状态流转与监控点

下面的 SVG 图展示了连接池内部的状态机，以及每个状态对应的 DB.Stats() 字段：

4.3 实战：采集与输出连接池指标

以下代码演示了如何定期调用 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()

        // 计算平均等待时间（纳秒）
        avgWaitNs := int64(0)
        if stats.WaitCount > 0 {
            avgWaitNs = stats.WaitDuration.Nanoseconds() / stats.WaitCount
        }

        // 计算连接使用率
        usageRate := 0.0
        if stats.MaxOpenConnections > 0 {
            usageRate = float64(stats.InUse) / float64(stats.MaxOpenConnections) * 100
        }

        log.Printf("[连接池状态] "+
            "Open=%d | InUse=%d | Idle=%d | "+
            "WaitCount=%d | AvgWait=%dms | "+
            "MaxOpen=%d | UsageRate=%.1f%% | "+
            "MaxIdleClosed=%d | MaxLifetimeClosed=%d",
            stats.OpenConnections,
            stats.InUse,
            stats.Idle,
            stats.WaitCount,
            avgWaitNs/1e6, // 转换为毫秒
            stats.MaxOpenConnections,
            usageRate,
            stats.MaxIdleClosed,
            stats.MaxLifetimeClosed,
        )

        // 告警阈值示例
        if stats.WaitCount > 0 && avgWaitNs > 100*1e6 { // 平均等待超过100ms
            log.Printf("[WARN] 连接池等待延迟过高: %dms", avgWaitNs/1e6)
        }
        if stats.MaxOpenConnections > 0 && usageRate > 85 {
            log.Printf("[WARN] 连接池使用率超过85%%: %.1f%%", usageRate)
        }
    }
}

func main() {
    // 假设 db 已经通过 sql.Open() 初始化
    // db, _ := sql.Open("mysql", dsn)
    // go monitorPool(db, 5*time.Second)

    fmt.Println("监控协程已启动，每5秒采集一次连接池状态")
}

4.4 指标解读与常见问题模式

通过 DB.Stats() 的指标组合，可以快速诊断连接池的常见问题：

4.5 将指标接入 Prometheus 与 Grafana

在生产环境中，建议将 DB.Stats() 的指标暴露为 Prometheus Gauge 或 Counter，实现可视化监控。下面是一个简单的 Prometheus 指标注册示例：

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

var (
    dbOpenConns = promauto.NewGauge(prometheus.GaugeOpts{
        Name: "db_open_connections",
        Help: "当前打开的数据库连接数",
    })
    dbInUseConns = promauto.NewGauge(prometheus.GaugeOpts{
        Name: "db_inuse_connections",
        Help: "当前正在使用的数据库连接数",
    })
    dbIdleConns = promauto.NewGauge(prometheus.GaugeOpts{
        Name: "db_idle_connections",
        Help: "当前空闲的数据库连接数",
    })
    dbWaitCount = promauto.NewCounter(prometheus.CounterOpts{
        Name: "db_wait_count_total",
        Help: "累计等待获取连接的次数",
    })
    dbWaitDuration = promauto.NewCounter(prometheus.CounterOpts{
        Name: "db_wait_duration_seconds_total",
        Help: "累计等待获取连接的总时长（秒）",
    })
)

func collectDBStats(stats sql.DBStats) {
    dbOpenConns.Set(float64(stats.OpenConnections))
    dbInUseConns.Set(float64(stats.InUse))
    dbIdleConns.Set(float64(stats.Idle))
    dbWaitCount.Add(float64(stats.WaitCount)) // 注意：Stats() 返回的是累计值，需用 Add 而非 Set
    dbWaitDuration.Add(stats.WaitDuration.Seconds())
}