Add diagnostics_channel tracing

[logaretm]

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

Without subscribers there is no measurable overhead, so existing users shouldn't be affected. The benchmark run keeps every scenario within its noise (-2.1% to +3.6%) and flags none of them. 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:connect	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

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 }
    // client: { database, host, port, user, 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
• graphql-js

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.

[logaretm]

@charmander @brianc I closed the previous PR to clean up a few things. I would love to get feedback on this. I got a few points worth noting/discussing:

Argument sanitization

APMs usually sanitize arguments, the redis implementation for tracing channels actually takes this into account but I don't think this is needed for SQL since parameterized queries already separate the statement from the values. This PR emits query.text but not query.values, which is the same approach taken by OTel.

https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/packages/instrumentation-pg/src/utils.ts#L268-L271

Documentation

I haven't yet documented any of this, would something like this work here? Happy to add a doc covering channel names, payload shapes, and usage examples once the API is agreed on.

[Copilot]

Pull request overview

Adds first-class diagnostics_channel / TracingChannel instrumentation to pg and pg-pool so query/connection/pool lifecycles can be observed via subscribers instead of monkey-patching.

Changes:

• Introduces pg:query and pg:connection TracingChannels and wires them into Client#query and Client#connect.
• Introduces pg:pool:connect TracingChannel plus pg:pool:release / pg:pool:remove channels and wires them into pool lifecycle paths.
• Adds unit tests validating emitted events and context payloads (skipping unstable Node versions).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/pg/lib/diagnostics.js	Creates/query/connection tracing channels and shouldTrace() helper.
packages/pg/lib/client.js	Wraps connect() / query() callbacks with TracingChannel#traceCallback.
packages/pg/test/unit/client/diagnostics-tests.js	Adds unit tests for pg:query and pg:connection tracing.
packages/pg-pool/diagnostics.js	Creates pool diagnostics channels and shouldTrace() helper.
packages/pg-pool/index.js	Publishes pool connect/release/remove lifecycle events.
packages/pg-pool/test/diagnostics.js	Adds tests for pool tracing + publish-only channels.

---

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

[logaretm]

@brianc friendly ping. I added docs and adjusted some areas for OTel alignment.

Since last change here we shipped this in GraphQL and Nitro with more libraries in the ecosystem adopting tracing channels. is there anything I can help with or clarify?

[logaretm]

@brianc Sorry to ping again. At the moment all those frameworks and libraries have adopted tracing channels, and pg remains one of the top libraries in the ecosystem that hasn't.

Since April, these have adopted it as well:

• node-redis, via redis/node-redis#3195
• ioredis, via redis/ioredis#2089
• Nitro, via nitrojs/nitro#4001
• GraphQL.js, via graphql/graphql-js#4670
• Mongoose, via Automattic/mongoose#16275
• Nuxt, via nuxt/nuxt#35191
• Vercel AI SDK, via vercel/ai#15660
• db0, via unjs/db0#193
• Express, via pillarjs/router#196

Node.js also marked TracingChannel as stable in nodejs/node#64525.

Is there a specific blocker I can help with or address? Perhaps I could split this into smaller PRs (one for the query channels and one for the pool)?