Add diagnostics_channel TracingChannel support

[jwangxx]

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.

[Copilot]

Pull request overview

This PR adds Node.js diagnostics_channel TracingChannel support to the pg and pg-pool packages so that APM/observability tooling can instrument query, connection, and pool lifecycles by subscribing to channels rather than monkey-patching. New diagnostics.js modules lazily resolve the built-in diagnostics_channel (with a Node 18/older fallback and a shouldTrace guard that no-ops when there are no subscribers), and the client/pool wire query, connection, and pool acquire/release/remove events through those channels.

Changes:

• Introduces pg:query and pg:connection tracing channels in pg, and pg:pool:connect (tracing) plus pg:pool:release/pg:pool:remove (plain) channels in pg-pool.
• Wraps Client#connect, Client#query, and Pool connect/release/remove paths with tracing that is fully skipped when no subscribers are present.
• Adds unit tests for both packages, guarded to skip on Node versions lacking a stable TracingChannel.

Show a summary per file

File	Description
packages/pg/lib/diagnostics.js	New module resolving pg:query/pg:connection tracing channels with a shouldTrace helper.
packages/pg/lib/client.js	Wraps connect and query callback paths with tracing when subscribers exist.
packages/pg/test/unit/client/diagnostics-tests.js	Unit tests for query/connection channels, skipped on unstable Node.
packages/pg-pool/diagnostics.js	New module resolving pool connect/release/remove channels.
packages/pg-pool/index.js	Publishes pool acquire/release/remove diagnostics events.
packages/pg-pool/test/diagnostics.js	Mocha tests for pool diagnostics channels.

Note: packages/pg-pool/diagnostics.js is added at the package root but is not part of the package's files allowlist, so it would be omitted from the published npm package and break require('./diagnostics') at load time — see the inline comment.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

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