feat(postgres): add Postgres.js tracing by BridgeAR · Pull Request #10125 · DataDog/dd-trace-js

BridgeAR · 2026-09-03T00:02:34Z

What does this PR do?

Adds automatic tracing for Postgres.js 3.x in CommonJS and ESM.

It starts spans when lazy queries enter a connection handler and finishes them at final Query settlement. Query identity and public methods remain unchanged.

The plugin reports compiled SQL resources, PostgreSQL database and endpoint tags, schema-aware names, peer service, truncation, and errors.

Motivation

Postgres.js is not currently instrumented, so applications using it do not emit database spans.

Its connection handlers and Query settlement functions remain in module-local closures, which makes runtime export wrapping incomplete.

Additional Notes

The real PostgreSQL matrix runs against 3.0.0 and 3.4.9 in CommonJS and ESM. It covers:

Unexecuted, deferred, mutated, and multiply-observed lazy queries.
Callback cursors, multi-batch async cursors, early return, and cursor errors.
COPY streams, file queries, build errors, server errors, and connection-ended errors.
Prepared-statement retries plus active and queued cancellation.
Transactions, reserved connections, concurrent pipelining, and parent propagation.
Multi-host metadata, naming schemas, service override, peer service, and truncation boundaries.

Postgres.js 1.x is excluded because it has a different internal architecture.

This does not add DBM propagation, AppSec query blocking, or a separate pool span.

Refs #2644

dd-octo-sts · 2026-09-03T00:03:24Z

Overall package size

Self size: 8.84 MB
Deduped: 9.51 MB
No deduping: 9.51 MB

Dependency sizes

| name | version | self size | total size | |------|---------|-----------|------------| | import-in-the-middle | 3.4.0 | 127.33 kB | 447.04 kB | | opentracing | 0.14.7 | 194.81 kB | 194.81 kB | | dc-polyfill | 0.1.11 | 25.74 kB | 25.74 kB |

_{🤖 This report was automatically generated by heaviest-objects-in-the-universe}

datadog-datadog-prod-us1 · 2026-09-03T00:05:49Z

✨ Unblock PR with BitsAI

⚠️ Warnings

❌ Your PR has failed checks. Please review the issues below and take necessary action before merging.

🚦 1 Pipeline job failed

DataDog/apm-reliability/dd-trace-js | validate_supported_configurations_v2_local_file — 🔧 Needs a code fix, caused by this PR

View more details · View in GitLab

ℹ️ Info

No other issues found (see more)

🧪 All tests passed
❄️ No new flaky tests detected

🔄 Datadog retried 1 test - 1 passed on retry

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 98.03% (-0.01%)

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: 6d2af20 | Docs | View more details | Give us feedback!}

codecov · 2026-09-03T00:17:35Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.65%. Comparing base (ca391e1) to head (6d2af20).

Additional details and impacted files

@@           Coverage Diff            @@
##           master   #10125    +/-   ##
========================================
  Coverage   98.65%   98.65%            
========================================
  Files        1005     1009     +4     
  Lines      157435   157847   +412     
  Branches       74       74            
========================================
+ Hits       155312   155724   +412     
  Misses       2123     2123

Flag	Coverage Δ
ai-guard	`64.80% <35.46%> (-0.22%)`	⬇️
apm-capabilities	`63.09% <60.44%> (-0.01%)`	⬇️
apm-integrations	`81.52% <100.00%> (+0.09%)`	⬆️
appsec	`58.64% <36.87%> (-0.08%)`	⬇️
debugger	`69.85% <83.33%> (+0.02%)`	⬆️
instrumentation	`53.78% <70.93%> (+0.04%)`	⬆️
llmobs	`78.76% <35.46%> (-0.26%)`	⬇️
master-coverage	`98.65% <100.00%> (?)`
openfeature	`66.40% <83.33%> (-0.02%)`	⬇️
platform	`69.32% <83.33%> (+<0.01%)`	⬆️
profiling	`66.76% <83.33%> (-0.01%)`	⬇️
serverless	`65.55% <36.47%> (-0.18%)`	⬇️
test-optimization	`82.53% <35.46%> (-0.16%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pr-commenter · 2026-09-03T00:19:16Z

Benchmarks

Benchmark execution time: 2026-09-04 23:38:18

Comparing candidate commit 6d2af20 in PR branch BridgeAR/2026-09-03-postgres-js with baseline commit ca391e1 in branch master.

📊 Benchmarking dashboard

Found 0 performance improvements and 0 performance regressions! Performance is the same for 2307 metrics, 6 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

🟩 = significantly better candidate vs. baseline
🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

Unstable benchmarks

These benchmarks have a confidence interval too wide to call a change; treat them as noise rather than signal.

scenario:appsec-iast-no-vulnerability-iast-enabled-default-config-24

unstable max_rss_usage [-25.727MB; +36.134MB] or [-7.831%; +10.999%]

scenario:appsec-iast-with-vulnerability-iast-enabled-default-config-20

unstable max_rss_usage [-11.922MB; +37.042MB] or [-3.371%; +10.474%]

scenario:debugger-line-probe-without-snapshot-20

unstable max_rss_usage [-8592.112KB; +10276.912KB] or [-5.058%; +6.049%]

scenario:debugger-line-probe-without-snapshot-26

unstable max_rss_usage [-13.870MB; +19.017MB] or [-5.557%; +7.619%]

scenario:encoders-0.4-immediate-flush-20

unstable max_rss_usage [-9.960MB; +7.352MB] or [-12.404%; +9.156%]

scenario:llmobs-encode-unicode-mixed-20

unstable max_rss_usage [-9273.591KB; +9243.991KB] or [-12.640%; +12.599%]

wconti27 · 2026-09-03T15:21:27Z

 tracer.use('pg', { truncate: 5000 });
 tracer.use('pino');
+tracer.use('postgres');
+tracer.use('postgres', { service: 'postgres-service' });


we are moving away from allowing configurable per integration service name, can this be removed along with the optional configuration

I believe doing this only for some is not ideal. Otherwise it is likely confusing for customers. I believe it would also require special handling to prevent it (I believe it is a generic functionality)

Postgres.js keeps lazy queries and connection handlers in module-local closures. A Query can also settle after cursor replacement or retry. Instrument the source-owned dispatch and settlement boundaries to keep one span across queues, cursors, retries, and cancellations. Fixes: #2644

Postgres.js retains host and port values when a socket path is active, which made Unix-socket spans report a TCP endpoint that was not used.

Postgres.js uses whole-program transforms that do not share the generic transform contract.

BridgeAR added the semver-minor label Sep 3, 2026

BridgeAR force-pushed the BridgeAR/2026-09-03-postgres-js branch 2 times, most recently from 8dcf731 to 51a4551 Compare September 3, 2026 15:08

BridgeAR marked this pull request as ready for review September 3, 2026 15:12

BridgeAR requested review from a team as code owners September 3, 2026 15:13

BridgeAR requested review from khanayan123 and wconti27 September 3, 2026 15:13

wconti27 reviewed Sep 3, 2026

View reviewed changes

Comment thread packages/datadog-instrumentations/src/helpers/rewriter/transforms.js Outdated

wconti27 reviewed Sep 3, 2026

View reviewed changes

BridgeAR marked this pull request as draft September 3, 2026 15:38

BridgeAR added 3 commits September 5, 2026 00:57

fix(postgres): omit TCP tags for Unix sockets

e366f06

Postgres.js retains host and port values when a socket path is active, which made Unix-socket spans report a TCP endpoint that was not used.

refactor(postgres): isolate rewriter transforms

6d2af20

Postgres.js uses whole-program transforms that do not share the generic transform contract.

BridgeAR force-pushed the BridgeAR/2026-09-03-postgres-js branch from 51a4551 to 6d2af20 Compare September 4, 2026 23:21

BridgeAR marked this pull request as ready for review September 7, 2026 10:05

Navigation Menu

Uh oh!

feat(postgres): add Postgres.js tracing - #10125

feat(postgres): add Postgres.js tracing#10125
BridgeAR wants to merge 3 commits into
masterfrom
BridgeAR/2026-09-03-postgres-js

BridgeAR commented Sep 3, 2026 •

edited

Loading

Uh oh!

dd-octo-sts Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

datadog-datadog-prod-us1 Bot commented Sep 3, 2026 •

edited by datadog-datadog-prod-us1-2 Bot

Loading

Uh oh!

codecov Bot commented Sep 3, 2026 •

edited

Loading

Uh oh!

pr-commenter Bot commented Sep 3, 2026 •

edited

Loading

Explanation

More details about the CI and significant changes

Unstable benchmarks

scenario:appsec-iast-no-vulnerability-iast-enabled-default-config-24

scenario:appsec-iast-with-vulnerability-iast-enabled-default-config-20

scenario:debugger-line-probe-without-snapshot-20

scenario:debugger-line-probe-without-snapshot-26

scenario:encoders-0.4-immediate-flush-20

scenario:llmobs-encode-unicode-mixed-20

Uh oh!

Uh oh!

wconti27 Sep 3, 2026

Uh oh!

BridgeAR Sep 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

BridgeAR commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Motivation

Additional Notes

Uh oh!

dd-octo-sts Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overall package size

Uh oh!

datadog-datadog-prod-us1 Bot commented Sep 3, 2026 • edited by datadog-datadog-prod-us1-2 Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Warnings

ℹ️ Info

Uh oh!

codecov Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pr-commenter Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarks

Explanation

More details about the CI and significant changes

Unstable benchmarks

scenario:appsec-iast-no-vulnerability-iast-enabled-default-config-24

scenario:appsec-iast-with-vulnerability-iast-enabled-default-config-20

scenario:debugger-line-probe-without-snapshot-20

scenario:debugger-line-probe-without-snapshot-26

scenario:encoders-0.4-immediate-flush-20

scenario:llmobs-encode-unicode-mixed-20

Uh oh!

Uh oh!

wconti27 Sep 3, 2026

Choose a reason for hiding this comment

Uh oh!

BridgeAR Sep 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BridgeAR commented Sep 3, 2026 •

edited

Loading

dd-octo-sts Bot commented Sep 3, 2026 •

edited

Loading

datadog-datadog-prod-us1 Bot commented Sep 3, 2026 •

edited by datadog-datadog-prod-us1-2 Bot

Loading

codecov Bot commented Sep 3, 2026 •

edited

Loading

pr-commenter Bot commented Sep 3, 2026 •

edited

Loading