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.

[Copilot]

🟡 Changes recommended

Packaging, tracing correctness, compatibility, and coverage issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

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

Changes:

• Adds query, connection, and pool diagnostic channels.
• Instruments callback and promise-based operations.
• Adds diagnostics unit tests.

File summaries

File	Description
packages/pg/test/unit/client/diagnostics-tests.js	Tests client tracing behavior.
packages/pg/lib/diagnostics.js	Initializes PostgreSQL tracing channels.
packages/pg/lib/client.js	Instruments client connections and queries.
packages/pg-pool/test/diagnostics.js	Tests pool diagnostics.
packages/pg-pool/index.js	Publishes pool lifecycle events.
packages/pg-pool/diagnostics.js	Initializes pool diagnostic channels.

Review details

Suppressed comments (9)

packages/pg-pool/diagnostics.js:12

• The Node API is named process.getBuiltinModule, not process.getBuiltInModule, so this branch is never taken on Node versions that provide the built-in module accessor. In runtimes where the require fallback is unavailable, diagnostics are then silently disabled; use the actual API name.

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

packages/pg-pool/diagnostics.js:32

• The same Node 18 fallback makes shouldTrace(poolConnectChannel) true even with no subscribers, so every pool connection allocates tracing context and callback wrappers. This adds avoidable overhead to a hot pool path; use a version-safe check of the underlying channels rather than treating an undefined aggregate as subscribed.

  return channel.hasSubscribers !== false

packages/pg-pool/index.js:218

• The pool connect tracing call uses the same invalid argument order, making 0 the published context and preventing subscribers from receiving the pool/client context. Pass context as the second argument, null as thisArg, and enrichedCb as the operation callback.

      poolConnectChannel.traceCallback(

packages/pg/lib/client.js:709

• Checking query.callback excludes the supported client.query(new Query(...)) event-emitter form: that path intentionally has no callback and completes through query.emit('end')/error, so it produces no pg:query start, asyncEnd, or error events. Trace that lifecycle too, or document that this channel is callback/promise-only.

    if (shouldTrace(queryChannel) && query.callback) {

packages/pg/lib/client.js:215

• TracingChannel.traceCallback takes (fn, context, thisArg, ...args), but this passes 0 as the context and the context object as thisArg. Subscribers will receive 0 instead of the connection context, and the callback factory's arguments are shifted; pass context second, null third, and callback as the operation argument.

        connectionChannel.traceCallback((tracedCb) => this._connect(tracedCb), 0, context, null, callback)

packages/pg/lib/client.js:231

• The promise overload repeats the incorrect traceCallback argument order: 0 becomes the tracing context, so pg:connection subscribers do not receive the object built above and the callback wrapper is misapplied. Use the context as the second argument and the callback as the only operation argument.

        connectionChannel.traceCallback((tracedCb) => this._connect(tracedCb), 0, context, null, callback)

packages/pg/lib/client.js:726

• This traceCallback call has the same shifted arguments: 0 is published as the query context and the callback factory receives the wrong arguments, so the new query lifecycle notifications cannot carry the context/result data. Pass context, null, enrichedCb after the factory.

      queryChannel.traceCallback(

packages/pg/lib/client.js:723

• Query.handleReadyForQuery can pass an array of results for multi-statement queries, but this always reads rowCount and command directly from res. Those traces consequently publish undefined result fields and lose the per-statement data; preserve the array or map each result before assigning the context.

        if (res) context.result = { rowCount: res.rowCount, command: res.command }

packages/pg/lib/diagnostics.js:11

• The Node API is named process.getBuiltinModule, not process.getBuiltInModule, so this branch is never taken on Node versions that provide the built-in module accessor. In runtimes where the require fallback is unavailable, diagnostics are then silently disabled; use the actual API name.

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

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

---

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