📚 课程目录第4章 OTel简介

4. OTel 简介：OpenTelemetry 是什么、三大信号（Trace/Metric/Log）、OTel 在连接池监控中的角色

在深入连接池水位监控之前，必须先理解监控数据的来源与标准。OpenTelemetry（简称 OTel）是目前业界公认的可观测性标准框架，它统一了遥测数据的采集、关联与导出方式。本章将阐明 OTel 的核心概念、三大信号及其在连接池监控中的具体定位。

4.1 什么是 OpenTelemetry

OpenTelemetry 是一个开源的可观测性框架与标准，由 Cloud Native Computing Foundation（CNCF）孵化。它提供了一组 API、SDK 和工具，用于从应用程序中生成、采集、关联和导出遥测数据。其核心目标是为 Trace、Metric 和 Log 提供统一的规范，避免厂商锁定。

  核心价值：OTel 不是一种监控产品，而是一个数据采集与标准化层。它让开发者只需接入一次，即可将数据发送到 Prometheus、Jaeger、Zipkin、Datadog 等多种后端。

4.2 三大信号：Trace、Metric、Log

OTel 定义了三种主要的遥测信号，它们从不同维度描述系统状态，在连接池监控中各有侧重。

信号	定义	连接池监控中的角色
Trace（链路）	记录一次请求在分布式系统中的完整路径，包含 Span（跨度）和 Span 间的父子关系。	追踪每个数据库请求从获取连接到释放连接的完整生命周期，定位慢查询或连接泄漏。
Metric（指标）	聚合后的数值型数据，如计数、直方图、平均值，用于衡量系统状态。	实时监控连接池的活跃连接数、空闲连接数、等待队列长度、获取连接耗时等水位指标。
Log（日志）	带有时间戳的结构化或非结构化文本记录，描述离散事件。	记录连接池的创建、销毁、超时、拒绝等关键事件，辅助排查异常。

关键认知：三大信号并非孤立存在。OTel 通过 TraceId、SpanId 和 Resource 属性将 Trace、Metric 和 Log 关联起来，形成完整的可观测性视图。例如，当 Metric 显示连接池水位过高时，可以关联到具体的 Trace 查看是哪个请求占用了连接，再结合 Log 查看该请求的详细错误。

4.3 OTel 在连接池监控中的角色

OTel 在连接池水位监控中扮演着“数据管道”与“关联桥梁”的双重角色。它不直接管理连接池，而是负责将连接池内部的状态转化为标准化的遥测数据，并确保这些数据可以被关联分析。

4.4 连接池监控中的三大信号具体应用

下面通过一个典型的连接池操作流程，展示三大信号如何协同工作。

4.4.1 Trace：追踪连接生命周期

当应用发起一次数据库查询时，OTel 会创建一个 Trace。该 Trace 包含多个 Span：

获取连接 Span：记录从连接池申请连接的开始与结束时间，包含等待队列耗时。
数据库查询 Span：记录 SQL 执行时间、影响行数等。
释放连接 Span：记录连接归还到连接池的时间点。

通过 Trace，可以精确判断连接获取耗时是否过长，以及是哪个业务请求导致了连接池压力。

4.4.2 Metric：实时水位指标

OTel 通过 Meter API 采集连接池的聚合指标，典型指标包括：

指标名称	类型	说明
`db.connection.active`	UpDownCounter	当前活跃连接数
`db.connection.idle`	UpDownCounter	当前空闲连接数
`db.connection.max`	Gauge	连接池最大连接数配置
`db.connection.wait_time`	Histogram	获取连接等待时间分布
`db.connection.timeouts`	Counter	连接超时次数

4.4.3 Log：记录关键事件

当连接池发生异常或状态变更时，OTel 会输出结构化日志，例如：

{
  "timestamp": "2025-03-21T10:30:00.123Z",
  "severity": "WARN",
  "body": "Connection pool exhausted, waiting for connection",
  "attributes": {
    "db.connection.pool.name": "primary-pool",
    "db.connection.active": 50,
    "db.connection.max": 50,
    "db.connection.waiting": 5
  }
}

常见误区：不要只依赖 Log 来监控连接池水位。Log 是离散事件，无法反映连续变化；Metric 才是水位监控的主力。Log 应作为 Trace 和 Metric 的补充，用于记录异常事件和上下文信息。

4.5 OTel 在连接池监控中的优势总结

标准化：统一的数据模型和 API，避免为不同后端编写不同的采集代码。
关联性：通过 TraceId 和 Resource 属性，将 Trace、Metric、Log 关联到同一个连接池实例和请求上下文。
可扩展：支持自动插桩（如 JDBC 拦截器）和手动插桩，灵活适配 HikariCP、DBCP 等不同连接池实现。
厂商中立：数据可以导出到 Prometheus、Jaeger、Datadog 等任意兼容后端，避免锁定。