Add `diagnostics_channel` tracing by logaretm · Pull Request #3650 · brianc/node-postgres

logaretm · 2026-04-07T19:14:22Z

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:

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 · 2026-04-07T19:18:18Z

@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 · 2026-06-02T19:22:03Z

@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?

Publishes pg:query and pg:connection tracing channels from the client, and pg:pool:connect, pg:pool:release and pg:pool:remove from the pool, so instrumentation libraries can subscribe instead of monkey-patching. All publishing is skipped when there are no subscribers. Closes brianc#3619

…ribers

logaretm · 2026-10-09T16:29:18Z

@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)?

…ch PRs 16 git cases pinned to commit SHAs: - sequelize, jsonparser, cJSON, Cachet security fixes (from their GitHub advisories), each as fix (approve), honest revert (reject), and revert with a misleading description (reject) - ReviewBench k1LoW/gh-copilot-review#9, AA-Factory/aafactory-prototype#17, brexhq/CrabTrap#15, brianc/node-postgres#3650 (reject); target findings from ReviewBench golden/ Checked when added: all repos fetch and build, every reversal exactly undoes its fix, no target_issue text appears in any prompt. Dry run: 32 calls (16 cases x 2 templates), ~439k prompt tokens, worst case ~$0.47 on GLM-4.6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

#73) The driver now publishes diagnostics_channel events that APM tools can subscribe to without patching it. Nothing is published, and nothing is allocated, while a channel has no subscriber. TracingChannels, each following tracePromise order (start, end, error, asyncStart, asyncEnd) and settling once: - postgres:query, one per query, started in Query.handle in the caller's async context so a bindStore transform sees it. The text and statement name are filled in when the query is built for a connection. - postgres:connect, one per connection acquisition, from the socket attempt through the first ReadyForQuery. - postgres:pool:connect, one per wait for a connection: every plain query inside its query span, and every sql.reserve() and sql.begin(). - postgres:transaction, for sql.begin() and sql.savepoint(), with result.committed once known. Plain channels: postgres:pool:release when a reserved connection or transaction lets go of its connection, and postgres:pool:remove when a connection closes. The payload follows the field names of brianc/node-postgres#3650: query { text, name } and client { database, host, port, user, ssl, processID } on queries, connection {...} on connect, pool { totalCount, idleCount, waitingCount, maxSize } then client { processID, reused } on the pool span, and { client: { processID }, error } on release and remove. The pool span splits the wait. It starts when the request is routed. assign() records handoverTime, the moment a connection took the request over, and queuedBehind, how many queries that connection already had running or waiting. A query's span ends when the connection makes it its active query, so the time from handoverTime to the end is spent behind those queries, and the time before it is the wait for a connection. A request that is refused, cancelled or lost before then fails the pool span first and then itself. Not published: parameter values, in any payload; a send event; a channel for LISTEN or subscriptions. Internal queries (type fetching, session checks) are not traced. Each hook sits on a single transition of the request lifecycle: Query.handle, build, succeed/fail, assign, activate, the connection's acquisition and close, and the lease release. Types, docs/api.md, a workerd scenario, an A/B input for the Workers CPU job and tests/tracing.js cover it.

#73) The driver now publishes diagnostics_channel events that APM tools can subscribe to without patching it. Nothing is published, and nothing is allocated, while a channel has no subscriber. TracingChannels, each following tracePromise order (start, end, error, asyncStart, asyncEnd) and settling once: - postgres:query, one per query, started in Query.handle in the caller's async context so a bindStore transform sees it. The text and statement name are filled in when the query is built for a connection. - postgres:connect, one per connection acquisition, from the socket attempt through the first ReadyForQuery. - postgres:pool:connect, one per wait for a connection: every plain query inside its query span, and every sql.reserve() and sql.begin(). - postgres:transaction, for sql.begin() and sql.savepoint(), with result.committed once known. Plain channels: postgres:pool:release when a reserved connection or transaction lets go of its connection, and postgres:pool:remove when a connection closes. The payload follows the field names of brianc/node-postgres#3650: query { text, name } and client { database, host, port, user, ssl, processID } on queries, connection {...} on connect, pool { totalCount, idleCount, waitingCount, maxSize } then client { processID, reused } on the pool span, and { client: { processID }, error } on release and remove. The pool span splits the wait. It starts when the request is routed. assign() records handoverTime, the moment a connection took the request over, and queuedBehind, how many queries that connection already had running or waiting. A query's span ends when the connection makes it its active query, so the time from handoverTime to the end is spent behind those queries, and the time before it is the wait for a connection. A request that never reached a connection (refused, cancelled in the queue, connection attempt failed) fails the pool span first and then itself. Once handed over, the pool span resolves, and a later failure fails only the query span. Not published: parameter values, in any payload; a send event; a channel for LISTEN or subscriptions. Internal queries (type fetching, session checks) are not traced. Each hook sits on a single transition of the request lifecycle: Query.handle, build, succeed/fail, assign, activate, the connection's acquisition and close, and the lease release. Types, docs/api.md, a workerd scenario, an A/B input for the Workers CPU job and tests/tracing.js cover it.

#73) The driver now publishes diagnostics_channel events that APM tools can subscribe to without patching it. Nothing is published, and nothing is allocated, while a channel has no subscriber. TracingChannels, each following tracePromise order (start, end, error, asyncStart, asyncEnd) and settling once: - postgres:query, one per query, started in Query.handle in the caller's async context so a bindStore transform sees it. The text and statement name are filled in when the query is built for a connection. - postgres:connect, one per connection acquisition, from the socket attempt through the first ReadyForQuery. - postgres:pool:connect, one per wait for a connection: every plain query inside its query span, and every sql.reserve() and sql.begin(). - postgres:transaction, for sql.begin() and sql.savepoint(), with result.committed once known. Plain channels: postgres:pool:release when a reserved connection or transaction lets go of its connection, and postgres:pool:remove when a connection closes. Release carries an error only when the connection is terminated instead of returned healthy. The payload follows the field names of brianc/node-postgres#3650: query { text, name } and client { database, host, port, user, ssl, processID } on queries, connection {...} on connect, pool { totalCount, idleCount, waitingCount, maxSize } then client { processID, reused } on the pool span, and { client: { processID }, error } on release and remove. The pool span splits the wait. It starts when the request is routed. assign() records handoverTime, the moment a connection took the request over, and queuedBehind, how many queries that connection already had running or waiting. A query's span ends when the connection makes it its active query, so the time from handoverTime to the end is spent behind those queries, and the time before it is the wait for a connection. A request that never reached a connection (refused, cancelled in the queue, connection attempt failed) fails the pool span first and then itself. Once handed over, the pool span resolves, and a later failure fails only the query span. Not published: parameter values, in any payload; a send event; a channel for LISTEN or subscriptions. Internal queries (type fetching, session checks) are not traced. Each hook sits on a single transition of the request lifecycle: Query.handle, build, succeed/fail, assign, activate, the connection's acquisition and close, and the lease release. Types, docs/api.md, a workerd scenario, an A/B input for the Workers CPU job and tests/tracing.js cover it.

Copilot AI review requested due to automatic review settings April 7, 2026 19:14

Copilot started reviewing on behalf of logaretm April 7, 2026 19:15

View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Comment thread packages/pg/lib/diagnostics.js

Comment thread packages/pg/lib/client.js Outdated

Comment thread packages/pg-pool/diagnostics.js

logaretm mentioned this pull request Apr 7, 2026

diagnostics_channel: return original thenable nodejs/node#62407

Merged

logaretm mentioned this pull request May 26, 2026

Adopt TracingChannel for observability anthropics/anthropic-sdk-typescript#1036

Open

logaretm force-pushed the feat/diagnostics-channel branch 2 times, most recently from ce2eaaf to f722fef Compare June 2, 2026 19:19

logaretm force-pushed the feat/diagnostics-channel branch from fed4ead to cf9ce13 Compare June 2, 2026 19:51

logaretm force-pushed the feat/diagnostics-channel branch from cf9ce13 to 5d396e0 Compare August 6, 2026 16:44

logaretm mentioned this pull request Aug 6, 2026

Add pg TracingChannel support getsentry/sentry-javascript#23124

Open

logaretm force-pushed the feat/diagnostics-channel branch from 5d396e0 to de87909 Compare October 9, 2026 16:07

logaretm changed the title ~~Add diagnostics_channel TracingChannel support~~ Add diagnostics_channel tracing Oct 9, 2026

logaretm added 3 commits October 9, 2026 12:13

Skip tracing integration tests for the native client

db6f364

Rename pg:connection to pg:connect and drop processID from query context

f317cdc

docs: correct Node 18 behavior, failure event order and example subsc…

a7b5fec

…ribers

Publish the query Result as ctx.result instead of a summary

3cd58f2

okomarov mentioned this pull request Oct 24, 2026

feat: publish query, connection and transaction tracing channels (#73) steadybrew/postgresjs#192

Closed

okomarov mentioned this pull request Oct 25, 2026

Request lifecycle restructure and native tracing channels (#73) steadybrew/postgresjs#196

Draft

Navigation Menu

Repository navigation

Add `diagnostics_channel` tracing - #3650

Add `diagnostics_channel` tracing#3650
logaretm wants to merge 5 commits into
brianc:masterfrom
logaretm:feat/diagnostics-channel

logaretm commented Apr 7, 2026 •

edited

Loading

Uh oh!

logaretm commented Apr 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

logaretm commented Jun 2, 2026 •

edited

Loading

Uh oh!

logaretm commented Oct 9, 2026 •

edited

Loading

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

logaretm commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Usage

Uh oh!

logaretm commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Argument sanitization

Documentation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

logaretm commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

logaretm commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

logaretm commented Apr 7, 2026 •

edited

Loading

logaretm commented Apr 7, 2026 •

edited

Loading

logaretm commented Jun 2, 2026 •

edited

Loading

logaretm commented Oct 9, 2026 •

edited

Loading