Add diagnostics_channel TracingChannel support

[zhanglongtu]

This PR introduces tracing channels support to pg-pool and pg querying methods as discussed in #3619

I haven't yet run a benchmark, but without active tracing or subscribers the overhead is non-existent so existing users shouldn't be affected. The overhead would come from the consumers of the diag channels published here which is done anyways via monkey patching.

I added the following channels:

Channel	Type	Package	Description
pg:query	TracingChannel	pg	Query lifecycle (start, end, error with async context)
pg:connection	TracingChannel	pg	Client connection lifecycle
pg:pool:connect	TracingChannel	pg-pool	Pool connection acquisition lifecycle
pg:pool:release	Channel	pg-pool	Client released back to pool
pg:pool:remove	Channel	pg-pool	Client removed from pool

I understand there may be hesitation given that AI tooling was used in the implementation. To be clear, this isn't a drive-by contribution. I designed the channel layout, wrote the proposal document, and iterated through multiple rounds to handle real edge cases (Node 18 compat, preserving custom Promise types, hasSubscribers guards). The AI assisted with the code, but the approach and decisions are mine.

Usage

Instrumentations will only need to subscribe to tracing channels to create traces, logs or metrics:

import { tracingChannel } from 'diagnostics_channel'

tracingChannel('pg:query').subscribe({
  start({ query, client }) {
    // start span
    // query: { text, name, rowMode }
    // client: { database, host, port, user, processID, ssl }
  },
  asyncEnd({ query, result }) {
    // end span
    // result: { rowCount, command }
  },
  error({ query, error }) {
    // record error on span
  },
})

This is part of a broader initiative to bring TracingChannel support to the most widely used Node.js database and cache libraries. The same pattern has already been merged and shipped in:

• mysql2
• node-redis
• ioredis

I have been directly involved in those prior implementations and I'm happy to own this through to release, address any feedback, and provide whatever support is needed. Would love to hear your thoughts.

Supersedes #3624.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: e1f6deaf-51b2-400e-9ac5-4c6b3681d04b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

🟡 Changes recommended

Critical callback and packaging defects, plus unresolved tracing behavior issues, block approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds diagnostics_channel tracing for pg queries/connections and pg-pool lifecycle events.

Changes:

• Adds PostgreSQL query and connection tracing channels.
• Adds pool connection, release, and removal diagnostics.
• Adds diagnostic behavior tests.

File summaries

File	Summary and final findings
packages/pg/test/unit/client/diagnostics-tests.js	Tests query and connection diagnostics.
packages/pg/lib/diagnostics.js	Defines pg channels. Moderate (2 votes): subscriber detection defeats the no-overhead path. Moderate (1 vote): misspelled getBuiltinModule fallback.
packages/pg/lib/client.js	Instruments client connections and queries. Critical (1 vote): incorrect tracing callback arguments. Moderate (2 votes): native client is not instrumented. Moderate (1 vote): array query results lose metadata. Moderate (1 vote): query timeouts bypass tracing.
packages/pg-pool/test/diagnostics.js	Tests pool diagnostics.
packages/pg-pool/index.js	Publishes pool lifecycle events. Critical (1 vote): incorrect tracing callback arguments. Critical (3 votes): diagnostics.js is omitted from the package tarball.
packages/pg-pool/diagnostics.js	Defines pool channels. Moderate (2 votes): subscriber detection defeats the no-overhead path. Moderate (1 vote): misspelled getBuiltinModule fallback.

Review details

Suppressed comments (4)

packages/pg-pool/diagnostics.js:12

• process.getBuiltInModule is misspelled; Node exposes process.getBuiltinModule (without the capital I). This branch is therefore never taken on Node, so the implementation always falls back to require('diagnostics_channel'), defeating the loader-safe built-in-module path intended for bundlers and alternate runtimes.

  if (typeof process.getBuiltInModule === 'function') {
    dc = process.getBuiltInModule('diagnostics_channel')

packages/pg/lib/client.js:724

• Client#query can return an array for a valid multi-statement simple query, but this branch treats every truthy result as one result object. The resulting asyncEnd payload is { rowCount: undefined, command: undefined } for those queries, so handle array results explicitly (or define an aggregate shape) instead of silently dropping their metadata.

      const enrichedCb = (err, res) => {
        if (res) context.result = { rowCount: res.rowCount, command: res.command }
        return origCb(err, res)

packages/pg/lib/client.js:724

• When query_timeout is enabled, the timeout handler closes over queryCallback and calls it directly, while this code only replaces query.callback. As a result, timed-out queries invoke the user's callback but bypass the tracing wrapper, so pg:query never publishes the timeout's error/asyncEnd lifecycle; route the timeout callback through the traced callback while preserving the timeout timer cleanup on normal completion.

      const origCb = query.callback
      const enrichedCb = (err, res) => {
        if (res) context.result = { rowCount: res.rowCount, command: res.command }
        return origCb(err, res)

packages/pg/lib/diagnostics.js:11

• process.getBuiltInModule is misspelled; Node exposes process.getBuiltinModule (without the capital I). This branch is therefore never taken on Node, so the implementation always falls back to require('diagnostics_channel'), defeating the loader-safe built-in-module path intended for bundlers and alternate runtimes.

  if (typeof process.getBuiltInModule === 'function') {
    dc = process.getBuiltInModule('diagnostics_channel')

• Files reviewed: 6/6 changed files
• Comments generated: 6
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.