4. OTel可观测性体系：Trace、Metric、Log三大信号，以及它们在连接池监控中的分工
在支付系统的连接池调优中，仅靠单一信号（如日志）无法定位并发瓶颈的全貌。OpenTelemetry（OTel）定义了三大可观测性信号——Trace（链路）、Metric（指标）、Log（日志），它们分别从不同维度描述系统状态。理解三者的分工与协同，是构建连接池水位监控体系的基础。
3.1 三大信号的定义与核心差异
| 信号类型 | 核心关注点 | 数据形态 | 典型问题 |
|---|---|---|---|
| Trace | 请求的完整调用链路与耗时分布 | Span树 + 上下文传播 | 哪个环节阻塞了连接获取？ |
| Metric | 聚合后的数值趋势与水位阈值 | 时间序列（Counter/Gauge/Histogram） | 连接池当前使用率是否接近上限？ |
| Log | 离散事件的详细上下文与异常堆栈 | 结构化文本 + 属性 | 连接超时时的具体错误码和参数是什么？ |
关键原则：Trace 回答“为什么慢”，Metric 回答“有多满”，Log 回答“具体发生了什么”。三者缺一不可。
3.2 连接池监控中的分工矩阵
在支付场景中，连接池瓶颈通常表现为：获取连接耗时飙升、活跃连接数触顶、等待队列堆积。三大信号在监控中的具体分工如下：
- Trace 负责：在每次数据库或下游 RPC 调用中，记录
acquire connection阶段的 Span 耗时。通过 Trace 可以精确判断“等待连接”与“执行 SQL”各自消耗了多少时间。 - Metric 负责：暴露连接池的核心指标，如
db.connection.pool.active（活跃连接数）、db.connection.pool.idle（空闲连接数）、db.connection.pool.wait_time（等待时间直方图）。这些指标用于设置告警阈值。 - Log 负责：当连接获取失败或超时时，输出包含 TraceID、连接池名称、当前水位、失败原因的日志条目。日志是事后排查的“最后一公里”。
实战建议：在支付核心链路上，务必为连接池操作添加
db.connection.pool.name 和 db.connection.state 属性，以便三大信号能够通过公共属性关联。
3.3 三大信号的协同关系（SVG架构图）
下图展示了在一次支付请求中，Trace、Metric、Log 如何围绕连接池协同工作：
3.4 信号关联的关键：公共属性
三大信号若各自孤立，则无法形成可观测性闭环。OTel 通过 属性（Attributes） 实现信号关联。在连接池监控中，必须统一注入以下公共属性：
db.connection.pool.name：连接池实例名称（如payment-write-pool）。db.connection.pool.state：连接状态（active/idle/pending）。db.connection.pool.wait_time_ms：等待时长（毫秒）。trace_id：当前请求的 TraceID，用于将 Log 与 Trace 关联。
常见陷阱：很多团队只采集 Metric 而忽略 Trace 中的连接等待 Span，导致告警触发后无法快速定位是哪个上游服务或哪个 SQL 语句导致了连接池耗尽。务必在 Trace 中显式记录
acquire connection 阶段。
3.5 连接池监控的典型数据流（SVG流程图）
下图展示了从连接请求到信号输出的完整数据流：
3.6 本章小结
| 信号 | 连接池监控职责 | 典型 OTel 语义约定 |
|---|---|---|
| Trace | 记录连接获取耗时、等待队列深度 | db.connection.wait_time Span Attribute |
| Metric | 暴露活跃/空闲/等待连接数、等待时间分布 | db.connection.pool.active Gauge |
| Log | 输出连接超时、获取失败的详细上下文 | 结构化日志包含 trace_id 和 pool_name |
核心结论：Trace 定位“哪个请求在等连接”，Metric 判断“连接池是否快满了”，Log 记录“失败时到底发生了什么”。三者通过公共属性关联，形成完整的连接池可观测性视图。下一章将深入 Metric 信号，讲解如何通过 Histogram 精确测量连接等待时间的分布。