[okomarov]

Adds native tracing through Node's diagnostics_channel (#73). APM tools such as Sentry, Datadog and OpenTelemetry can subscribe for query, connection, transaction and pool-wait spans instead of rewriting the driver's source, as dd-trace and Sentry do today. Channel names and payloads follow the pg tracing-channel PR (brianc/node-postgres#3650), so one integration can serve both drivers. Nothing is published or allocated unless something subscribes.

Why two parts

A request could reach a connection along several paths, queries and leases took different ones, and it could settle from several places. Tracing hooks would have been spread across all of them, so:

• Part 1 restructures the request lifecycle so each step happens in one place: one router, one hand-over, one point where a query starts, one settle. Behaviour is unchanged apart from the resolve/reject counts below.
• Part 2 adds the channels, each hooked at one of those places.

How pool waits are traced

pg checks a client out of the pool for every pool.query(), so its pool span covers every wait. Postgres.js has no checkout for plain queries, and it pipelines: when every connection is busy, it can send a query to a connection that is still running another one. So a query can wait in three places: in the pool queue, while a new connection opens, or behind another query on a busy connection.

postgres:pool:connect covers all three in one span, from asking for a connection until the connection starts the query. At hand-over it records handoverTime, which a subscriber can use to split it:

• Before it is the wait for a connection, OpenTelemetry's db.client.connection.wait_time. A connection opened for this query shows as a postgres:connect child span here.
• After it is the time queued behind other queries on that connection. queuedBehind says how many were ahead.

Pool Wait Spans compares this with the two alternatives (#192's, and a span that ends at hand-over).

Part 2: tracing channels (9722b28)

Channel	Kind	Covers
postgres:query	TracingChannel	every query, call to settlement
postgres:pool:connect	TracingChannel	every wait for a connection, for queries and leases
postgres:connect	TracingChannel	each connection attempt, including TLS and authentication
postgres:transaction	TracingChannel	sql.begin() and sql.savepoint(), with result: { committed }
postgres:pool:release	channel	a lease returning its connection; error only if the connection was lost
postgres:pool:remove	channel	a connection closing

No payload carries parameter values. docs/lifecycle.md lists the hook sites and docs/api.md the payloads.

Part 1: request lifecycle (a6b5623, 1c3bc59, 2970909)

• Every request, a Query or a lease, carries a stage (New, Queued, Opening, Sent, Active, Settled). step, succeed and fail in src/query.js are its only writers, and a request settles once.
• route is the one router for queries and leases, and never settles. assign is the one hand-over. A lease waits in the queue itself, so the separate waiter object is gone.
• The connection starts queries in one place, activate.
• The code shapes dd-trace rewrites are unchanged. The Sentry-range tracing variant is removed, because Sentry's rewrite only applies below 4.x.

The one behaviour difference: resolve and reject now run once per query (twice for COPY). Only code that wraps them sees it.

Path	main	here
sql\begin`` on a pool (UNSAFE_TRANSACTION)	1 resolve, 1 reject	0, 1
cancelled before it is awaited, max: 1	3 rejects	1
cancelled in a reserved connection's queue	3 rejects	1
cancelled in a transaction's queue	3 rejects	1

Evidence

Does this PR cost CPU?

Question	Who it affects	Measured
Does the restructure (Part 1) cost CPU against main?	everyone	no measurable change (p = 0.20)
Does tracing cost CPU when nothing subscribes?	everyone, since most users never trace	no measurable change (p = 0.18 against Part 1, 0.31 against main)
How much does tracing cost when an APM tool subscribes?	Sentry, Datadog and OTel users	under 1 ms per request: percentiles unchanged, rank test p = 0.015

Comparison on Cloudflare Workers	Run	Median	p95	p99	Costs more, p
Part 1 against main	40357338624	13 / 14 ms	20 / 20 ms	35 / 29 ms	0.20
Part 2 against Part 1, nothing subscribed	40360228129	20 / 21 ms	47 / 45 ms	54 / 50 ms	0.18
This branch against main, nothing subscribed	40357278590	11 / 11 ms	17 / 16 ms	29 / 23 ms	0.31
Every channel subscribed against nothing subscribed	40357291633	13 / 13 ms	19 / 19 ms	27 / 25 ms	0.015

• Each run deploys both builds in one Worker and runs 150 shuffled rounds of each. A round connects through Hyperdrive with prepare: true and fetch_types, runs four parameterized queries, three of them at once, and ends. CPU is Workers Logs cpuTimeMs in whole milliseconds; the test is a one-sided Mann-Whitney.
• The subscribed build binds an AsyncLocalStorage store to every tracing channel, as Sentry does, and subscribes no-op handlers to all six channels.
• The Part 2 run landed in 39 fresh isolates, which is why its numbers are higher. Requests that were first in their isolate cost 44 / 45 ms at the median, and later ones 18 / 18 ms, so the tracing code adds no visible cold-start cost either.
• Earlier runs with one unprepared select 1 per connection (40237682305, 40244172825, 40244200407, 40241580406) agree, but mostly measure connection setup. Per-query allocation is not measured.

npm run test:tracing shows dd-trace and Sentry behaving as on 3.4.9 on every commit, including COPY and a dd-trace run with every channel subscribed.