在分布式系统排查中，数据库往往被视为最神秘的 "黑盒"。应用层的 APM 工具可以清晰展示从 API 端到数据库驱动层的耗时，但 SQL 进入数据库后究竟经历了什么 —— 是 Planner 的复杂决策，还是 Executor 的低效执行，抑或是锁等待的僵局 —— 往往是一片空白。传统的 pg_stat_statements 只能提供统计聚合，auto_explain 又难以融入现代的分布式追踪体系。DataDog 开源的 pg_tracing 扩展正是为了填补这一空白：它旨在提供服务端（Server-side）的分布式追踪能力，且无需对 PostgreSQL 内核进行任何修改。
一、架构核心：纯扩展实现的低侵入性
pg_tracing 的设计哲学从一开始就非常明确："Don't require core changes"（无需核心更改）。PostgreSQL 提供了一套成熟的钩子（Hooks）机制，允许扩展在查询处理的关键生命周期节点注入自定义逻辑。pg_tracing 正是巧妙地利用了这些钩子，将追踪代码 "植入" 数据库的执行流程中，而无需像某些实验性功能那样必须修改内核代码。
这种实现方式带来了显著的优势。首先，部署门槛极低。用户只需在现有 PostgreSQL 实例上编译并加载扩展，无需重新编译数据库，也无需等待特定版本的发布。其次，独立性高。扩展的升级与维护完全由用户或社区控制，不受 PostgreSQL 核心发布周期的影响。
目前 pg_tracing 支持 PostgreSQL 14、15 和 16 版本，这些版本的钩子 API 相对成熟，为追踪提供了稳定的注入点。社区反馈也证实了这一点，PostgreSQL 资深开发者 Heikki Linnakangas 在邮件列表中评论道："能够在不修改核心的情况下实现这一点非常酷，因为你可以直接把代码放在 GitHub 上，人们就能立即开始使用它。"
二、追踪粒度：从 Planner 到并行 Worker 的全链路观测
pg_tracing 的追踪粒度之细，几乎覆盖了 SQL 在数据库内部处理的全流程。它不仅追踪宏观的语句执行，还深入到了执行计划的每一个节点。
1. 声明式语句与执行计划节点
当 pg_tracing 激活时，它会为采样的查询生成一系列 Span。对于每一条 SQL 语句，顶层会有一个 Query Span；如果在查询中包含了嵌套调用（如函数），每个嵌套层级都会生成独立的 Span。更进一步，对于执行计划中的每一个算子（如 SeqScan、IndexScan、HashJoin、NestedLoop），pg_tracing 都会生成对应的 Node Span，记录该节点的类型、耗时以及相关的执行统计信息（如 buffer usage、JIT 耗时、wal usage 等）。
2. 内部执行阶段
PostgreSQL 的查询执行分为多个阶段：Planner（优化）、Executor（执行）。pg_tracing 分别通过 planner_hook 和 ExecutorRun、ExecutorFinish 等钩子介入：
- Planner Span：记录查询优化的时间开销和代价估算，帮助判断慢查询是否源于优化器的低效。
- Executor Span：追踪
Start、Run、Finish三个核心步骤。
3. 高级特性追踪 pg_tracing 还不放过那些通常难以观测的区域：
- 触发器（Triggers）：无论是
BEFORE还是AFTER触发器触发的语句，都会被记录在父 Span 之下。 - 并行 Worker：在 PostgreSQL 开启并行查询时，Worker 进程中的执行细节也能被追踪到。
- 事务提交：甚至连
fsync等待的时间（事务 Commit 的关键路径）也被单独计量，这对于排查写入抖动至关重要。
三、上下文传播：如何让数据库 "认识" 外部的 TraceID
分布式追踪的核心是上下文（Context）的传递。客户端生成的 TraceID 如何传递给数据库，并在数据库内部被正确解析和关联？pg_tracing 采用了两种主要机制：
1. SQLCommenter（推荐） 这是目前 pg_tracing 推荐的方式。客户端驱动（如 DataDog 的 Go 探针）在发送 SQL 时，会在语句末尾追加注释：
/*dddbs='postgres.db',traceparent='00-00000000000000000000000000000009-0000000000000005-01'*/
SELECT * FROM users WHERE id = 1;
数据库接收到语句后，pg_tracing 会解析注释中的 traceparent 字段（W3C 标准），提取 TraceID 和 ParentID，从而将后续生成的 Span 正确地关联到全局追踪链中。
2. GUC 参数
作为备选方案，pg_tracing 也支持通过 PostgreSQL 的 GUC（Configuration Parameters）机制设置 pg_tracing.trace_context。这种方式的侵入性更低（无需修改 SQL），但在多租户或复杂连接池场景下配置相对繁琐。
四、与 Datadog APM 的集成架构
pg_tracing 本身是一个 "生成器"，它只负责在数据库内部产生 Span 数据。要将这些数据上报到 Datadog APM，还需要一个关键的中间组件：Span Forwarder（转发器）。
数据流路径
- 数据库内部：pg_tracing 将生成的 Span 存储在固定大小的共享内存缓冲区中。这种设计避免了将所有 Span 信息直接塞入内存导致数据库 OOM。同时，长文本信息（如查询语句文本）会被卸载到外部文件（类似
pg_stat_statements的处理方式）。 - 外部采集：Span Forwarder（一个独立部署的轻量级应用）通过调用
pg_tracing_json_spans()函数或查询视图（pg_tracing_consume_spans），从数据库中拉取 Span 数据。 - 协议转换与上报：Forwarder 根据配置，将 Span 构建为特定厂商所需的格式（如 OpenTelemetry OTLP JSON 或 Datadog Agent 期望的格式），并通过 HTTP/gRPC 协议推送给 Datadog Agent 或直接推送到 Collector。
这种架构的优势在于解耦。pg_tracing 扩展本身是厂商无关的，它只输出标准化的数据结构；Forwarder 负责处理所有与厂商相关的逻辑，使得数据库扩展无需关心 Datadog 的具体上报协议。
五、性能开销与工程实践要点
在生产环境启用追踪，核心关切是性能损耗。pg_tracing 虽然设计精巧，但生成 Span 本身是需要 CPU 和内存开销的。以下是需要关注的几个关键参数和配置点：
1. 共享内存配置
pg_tracing 使用共享内存缓冲区存储 Span。如果缓冲区满，新的 Span 生成会被阻塞或丢弃。需要在 postgresql.conf 中合理配置 pg_tracing.shared_memory_size，在观测深度和内存压力之间取得平衡。
2. 采样率（Sampling）
并非所有查询都需要追踪。W3C traceparent 头部中的 trace flags 字段标记了该请求是否需要采样（Sampled）。pg_tracing 只会对标记为采样的请求生成 Span。此外，用户也可以配置全量采样率来控制数据量。
3. 外部文件 I/O 对于包含大量参数的复杂查询，Span 中的文本信息会被写入外部文件。这虽然节省了共享内存，但也引入了文件 I/O 的开销。在极高 QPS 场景下，需要监控磁盘 I/O 是否成为瓶颈。
4. 监控与可观测性
pg_tracing 提供了 pg_tracing_info() 统计视图，用于监控当前的 Span 缓冲状态（已用 / 空闲），建议在监控系统中对这些指标进行持续观测，以便及时发现积压。
总结
pg_tracing 代表了数据库可观测性领域的一种新范式：在数据库内部用扩展的方式实现 APM。它巧妙地利用了 PostgreSQL 的钩子机制，以极低的侵入性换取了前所未有的服务端可见性。对于运维团队而言，这意味着可以更精确地定位慢查询的根源（是优化器、是执行算子，还是磁盘 I/O）；对于 DevOps 工程师而言，这意味着数据库不再是分布式追踪的盲区。如果你正在使用 PostgreSQL 且依赖 Datadog APM，pg_tracing 是一个值得密切关注并逐步引入生产环境的解决方案。
资料来源：