4. 连接池关键指标：活跃连接数、空闲连接数、等待队列长度、连接超时率、连接泄漏率

在 OAuth2.0 授权码模式与客户端凭证模式中，网关或微服务通常通过连接池与授权服务器（Authorization Server, AS）或资源服务器（Resource Server, RS）交互。连接池的健康状态直接决定认证链路的吞吐与稳定性。本章定义五项核心水位指标，并给出巡检阈值与故障判定逻辑。

4.1 指标定义与业务含义

4.2 指标关联与水位模型

连接池水位可抽象为三层状态机。下图展示从正常到故障的演进路径：

4.3 关键指标采集方式

以 Java 生态中最常用的 Apache HttpClient 和 OkHttp 为例，展示如何通过 JMX 或内置 Metrics 获取五项指标：

4.3.1 Apache HttpClient（PoolingHttpClientConnectionManager）

// 通过 JMX 或直接调用 PoolStats
PoolStats stats = connManager.getTotalStats();
int active = stats.getLeased();          // 活跃连接数
int idle   = stats.getAvailable();       // 空闲连接数
int pending= stats.getPending();         // 等待队列长度

// 超时率需自行计数
long timeoutCount = metricRegistry.counter("http.pool.timeout").getCount();
long totalCount   = metricRegistry.counter("http.pool.total").getCount();
double timeoutRate = (totalCount == 0) ? 0.0 : (double) timeoutCount / totalCount;

// 泄漏率通过 WeakRef 追踪
long createdCount = connManager.getTotalStats().getMax();
long returnedCount = ...; // 在连接归还时计数
double leakRate = (createdCount == 0) ? 0.0 :
    (double) (createdCount - returnedCount) / createdCount;

4.3.2 OkHttp（ConnectionPool）

ConnectionPool pool = client.connectionPool();
int idleCount = pool.idleConnectionCount();   // 空闲连接数
int totalCount = pool.connectionCount();      // 总连接数（活跃+空闲）
int active = totalCount - idleCount;          // 活跃连接数

// OkHttp 不直接暴露等待队列，需通过 Dispatcher 的 queuedCalls() 间接判断
int pending = client.dispatcher().queuedCallsCount();

4.4 连接泄漏检测与定位

连接泄漏是 OAuth2.0 场景中最隐蔽的故障。泄漏通常由以下原因引起：

• 未关闭响应流： 读取 HttpResponse.getEntity().getContent() 后未调用 close()。
• 异常路径未归还： try-catch 块中未在 finally 释放连接。
• 连接借出超时： 设置了 setConnectionRequestTimeout() 但未处理超时异常后的连接回收。

下图展示泄漏检测的典型流程：

4.5 巡检脚本示例（Prometheus + Grafana）

以下 PromQL 查询可直接用于 Grafana 面板，监控连接池水位：

# 活跃连接数占比
rate(http_client_connections_active[1m]) / http_client_connections_max

# 等待队列长度（需 exporter 暴露 gauge）
http_client_connections_pending

# 连接超时率（rate 计算）
rate(http_client_requests_timeout_total[5m]) / rate(http_client_requests_total[5m])

# 连接泄漏率（基于自定义 metric）
rate(http_client_connections_leaked_total[5m]) / rate(http_client_connections_created_total[5m])