在现代微服务架构中，数据库往往成为性能瓶颈的隐蔽角落。当一个用户请求跨越多个服务最终落在数据库上时，传统的应用层 APM 工具往往只能看到一条孤立的慢查询，而无法追溯这个查询在数据库内部的执行细节 —— planner 如何选择执行计划、哪些节点占据了大部分耗时、锁等待是如何发生的。这些信息的缺失使得数据库性能调优如同盲人摸象，难以精准定位问题根因。
pg_tracing 正是为解决这一困境而生的开源扩展。它由 Datadog 开发并维护，旨在为 PostgreSQL 提供服务器端的分布式追踪能力，将数据库内部的执行细节以 span 的形式暴露出来，使得运维团队能够端到端地追溯请求在数据库中的完整路径。本文将深入探讨如何利用 pg_tracing 构建 PostgreSQL 分布式追踪钩子，并将其集成到 Datadog APM 体系中，实现生产级的可观测性。
生产环境数据库可观测性的核心挑战
传统数据库监控手段主要依赖指标采集和日志分析。pg_stat_statements 等扩展能够统计查询的执行次数、平均耗时等聚合信息，但无法呈现单次查询的详细执行过程。当遇到偶发的性能毛刺时，我们只能看到某个查询变慢了，却不知道究竟是 planner 阶段的选择不当、还是某个 HashJoin 节点在处理大数据集、抑或是锁等待导致的时间膨胀。
更棘手的是分布式追踪在数据库层面的断裂。在微服务架构中，一个完整的用户请求可能经过 API 网关、应用服务器、消息队列，最终落在数据库上。应用层的分布式追踪能够将请求在各服务之间的调用关系串联起来，但数据库作为链路终点，往往只能被动地接收查询请求，无法主动参与追踪上下文的传递。这就导致追踪链条在数据库处断裂，运维人员无法将数据库内部的执行细节与上游服务调用关联起来。
pg_tracing 的出现正是为了填补这一空白。它通过 PostgreSQL 的扩展机制，在数据库内部埋入钩子，在查询执行的各个关键节点自动生成 span，从而构建起完整的数据库追踪链路。
pg_tracing 扩展架构与核心能力
pg_tracing 是一个 PostgreSQL 扩展，目前支持 PostgreSQL 14、15 和 16 版本。安装后，扩展会通过 PostgreSQL 的 hook 机制在查询执行的多个阶段注入追踪代码，自动捕获并记录执行过程中的关键信息。
从生成 span 的类型来看，pg_tracing 覆盖了查询执行的完整生命周期。在语句层面，它会为 SELECT、INSERT、UPDATE、DELETE 等 DML 语句以及 ALTER、SHOW、TRUNCATE 等 DDL 语句生成独立的 span。在执行计划层面，扩展会为每个执行计划节点创建 span，包括 SeqScan、NestedLoop、HashJoin、IndexScan 等常见节点类型。这种细粒度的追踪能力使得运维人员能够清晰地看到查询在执行计划中的每一步耗时分布。
此外，pg_tracing 还支持追踪嵌套查询、触发器语句、并行工作器进程以及事务提交过程。特别值得注意的是，事务提交阶段会单独记录 fsync 写入 WAL 的耗时，这对于排查事务提交延迟问题非常有价值。
扩展提供了两种方式访问生成的 span 数据。视图函数 pg_tracing_consume_spans 和 pg_tracing_peek_spans 可以将 span 以记录集的形式输出，便于直接在数据库中查询分析。而 pg_tracing_json_spans 函数则将 span 序列化为 OTLP JSON 格式，便于对接外部的追踪收集器。配合 pg_tracing_reset 和 pg_tracing_info 这两个实用函数，运维人员可以方便地读取扩展的统计信息并根据需要重置追踪状态。
追踪上下文传播机制
pg_tracing 支持两种追踪上下文传播机制，分别是 SQLCommenter 和 GUC 参数方式。SQLCommenter 是一种在 SQL 语句中嵌入追踪元数据的标准方法，应用层可以在发起查询时通过注释的方式注入 traceparent 等追踪头信息。例如，当应用层发送带有追踪上下文的查询 /*traceparent='00-00000000000000000000000000000123-0000000000000123-01'*/ SELECT 1 时，pg_tracing 会解析这个注释并自动将当前查询关联到对应的追踪链路中。
对于不便修改 SQL 语句的场景，pg_tracing 还支持通过会话级别的 GUC 参数传递追踪上下文。通过执行 SET LOCAL pg_tracing.trace_context='traceparent=''00-00000000000000000000000000000005-0000000000000005-01'''，后续在同一事务中执行的查询都会被自动关联到这个追踪上下文中。这种方式特别适合需要批量修改查询逻辑或使用 ORM 框架的场景。
当追踪上下文成功传播时，pg_tracing 生成的 span 会自动携带正确的 trace_id 和 parent_id，从而与上游服务的追踪链路串联起来。这种端到端的追踪能力是实现完整可观测性的关键基础。
集成 Datadog APM 的配置实践
pg_tracing 本身不直接与 Datadog Agent 通信，而是通过 OpenTelemetry 协议发送 span 数据。这使得它能够灵活地对接各种兼容 OTel 的追踪后端，包括 Datadog APM。
在 PostgreSQL 端的配置相对简单。首先需要在 postgresql.conf 中将 pg_tracing 添加到 shared_preload_libraries 列表中，这一步需要重启数据库才能生效。配置文件中还需要启用 compute_query_id 参数，因为 pg_tracing 依赖这个参数生成的查询标识符来关联追踪数据。
关键的追踪参数包括以下几个。pg_tracing.max_span 控制扩展使用的共享内存大小，单位是 span 数量，默认值通常足够应对中等负载，但高并发场景可能需要调大。pg_tracing.track 参数决定追踪哪些类型的语句，可选值包括 all、none 或具体语句类型列表。采样率则通过 pg_tracing.sample_rate 参数控制，设置为 1.0 表示追踪所有查询，在生产环境中通常会设置一个较低的采样比例以控制数据量和性能开销。
将 span 数据发送到 Datadog APM 需要配置 OTel 收集器端点。通过设置 pg_tracing.otel_endpoint 为 Datadog Agent 或 OTel Collector 的 OTLP HTTP 接收地址，扩展会在后台启动一个工作进程，定期批量发送 span 数据。pg_tracing.otel_naptime 参数控制发送间隔，默认为 2000 毫秒，这个值需要在数据时效性和网络开销之间取得平衡。
在 Datadog Agent 端，需要确保启用了接收 OTLP 数据的功能。Agent 会将接收到的 span 数据转发到 Datadog APM 服务端，运维人员就可以在 APM 界面中看到 PostgreSQL 查询的详细追踪信息。
生产部署的关键参数与监控清单
在生产环境中部署 pg_tracing 需要关注性能开销、内存使用和数据采样三个维度。首先是共享内存消耗，pg_tracing.max_span 设置的越大，扩展在启动时分配的内存就越多，这部分内存会在数据库整个生命周期中常驻。因此需要根据数据库的并发查询量和追踪需求合理规划这个值。一个保守的初始配置是 max_span=10000，然后根据实际监控数据逐步调整。
其次是采样策略的选择。对于 QPS 较高的数据库，追踪所有查询会产生大量数据，不仅增加网络传输和存储开销，还可能影响数据库性能。建议在高负载环境下将采样率设置为 0.01 到 0.1 之间，只保留一小部分有代表性的查询进行完整追踪。对于偶发的性能问题，可以临时提高采样率或针对特定查询启用独立追踪。
连接池指标的采集需要结合 PostgreSQL 的内置统计视图。pg_tracing 本身不直接暴露连接池使用情况，但可以通过定期查询 pg_stat_activity 和 pg_pool_status 等视图来补充这部分监控数据。将这些指标与追踪数据关联起来，能够更全面地分析查询性能与资源竞争之间的关系。
锁等待事件的追踪相对复杂，pg_tracing 没有直接提供锁等待的专用 span 类型。但可以通过监控 pg_locks 视图和追踪事务提交 span 来间接分析锁竞争情况。当发现某个查询的追踪 span 中事务提交阶段耗时异常时，往往意味着存在锁等待或 I/O 瓶颈。
建议建立以下监控告警规则：span 发送失败率监控，当后台工作进程无法成功发送 span 到 OTel 端点时触发告警；共享内存使用率监控，当已使用的 span 数量接近 max_span 限制时提示扩容；采样率自适应调整，根据数据库负载动态调整 pg_tracing.sample_rate 参数。
总结与最佳实践
pg_tracing 为 PostgreSQL 带来了原生级别的分布式追踪能力，使得数据库不再是可观测性的盲区。通过与 Datadog APM 的集成，运维团队能够端到端地追溯请求在数据库内部的执行细节，精准定位查询性能瓶颈。在实际部署中，建议从以下几个方面入手：首先确保 PostgreSQL 版本兼容（14-16），并在测试环境中验证扩展的稳定性；其次合理规划共享内存大小和采样策略，避免对生产数据库造成额外负担；最后建立完整的监控告警体系，确保追踪数据的持续可用性。
随着微服务架构的日益普及，数据库层面的可观测性将变得越来越重要。pg_tracing 的出现标志着 PostgreSQL 监控能力的一次质的飞跃，为构建全面的可观测性体系奠定了坚实基础。
资料来源：pg_tracing 官方 GitHub 仓库（https://github.com/datadog/pg_tracing）、Datadog PostgreSQL 数据库监控文档。