fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
main
agentic-dev/docs/library-decisions/2026-05-14-@opentelemetry/instrumentation-pg.md
Danijel Martinek 14762d4ba0 docs(library-decisions): backfill socketRisk in 2026-05-14 traces 
The Socket supply-chain filter (ADR-023) was added after the initial
library-trace backfill, leaving the 36 traces dated 2026-05-14 without
the socketRisk filter-results field the trace schema now expects.
Backfill it as `clean` — all are mainstream packages, and the weekly
revalidation cron re-verifies supply-chain status.
2026-05-20 17:02:13 +02:00

3.3 KiB
Raw Permalink Blame History

package, version, tier, decision, date, deciders, adr, filter-results, verification-commands, accepted-cves
package version tier decision date deciders adr filter-results verification-commands accepted-cves
@opentelemetry/instrumentation-pg ^0.50.0 core approved 2026-05-14
Danijel Martinek
adr-017
license types maintenance boundary-fit shadow-check eu-residency cve-scan named-consumer socketRisk
Apache-2.0 native active pass pass n/a clean pass clean
npm view @opentelemetry/instrumentation-pg license
npm view @opentelemetry/instrumentation-pg version
pnpm audit --audit-level=moderate

Filter: license

npm view @opentelemetry/instrumentation-pg license returns Apache-2.0. Apache-2.0 is on the allowlist.

Filter: types

@opentelemetry/instrumentation-pg is authored in TypeScript and ships its own .d.ts declaration files. No separate @types/ package is needed.

Filter: maintenance

Actively maintained by the OpenTelemetry community as the first-party PostgreSQL (pg) instrumentation plugin. The 0.50.x line is current and tracks the OTel SDK release cycle.

Filter: boundary-fit

ADR-017 §11 explicitly enables pg auto-instrumentation in initOtelServerNode with enhancedDatabaseReporting: false to prevent SQL statement capture (PII protection for WHERE clauses). Restricted to core-shared/instrumentation/otel/ init paths.

Filter: shadow-check

@opentelemetry/instrumentation-pg is the standard OTel PostgreSQL auto-instrumentation. No competing database span emitter is present in the workspace.

Filter: eu-residency

@opentelemetry/instrumentation-pg is a pure instrumentation plugin with no independent data transmission. Spans are routed through the configured OTel exporter. EU residency is governed by the exporter configuration.

Filter: cve-scan

pnpm audit --audit-level=moderate reports no advisories against @opentelemetry/instrumentation-pg at the time of this trace.

Filter: named-consumer

packages/core-shared/src/instrumentation/otel/init-otel-server-node.ts registers PgInstrumentation with enhancedDatabaseReporting: false (ADR-017 §11, R32). This emits database spans for every Payload CMS PostgreSQL query without capturing full SQL text that may contain PII.

Prompt: replaces

Manual database span wrapping around every pg query call site. The auto-instrumentation patches the pg module to emit spans automatically, including connection pooling and query timing data.

Prompt: migration-cost-out

Low. PgInstrumentation is registered in one init file. Removing it means disabling the plugin and optionally adding manual spans at pg query call sites — localized to the SDK init.

Prompt: alternatives-considered

  1. Manual pg spans — No plugin needed, but requires wrapping every Payload CMS / pg query explicitly. Rejected: Payload's query layer abstracts away direct pg calls, making manual wrapping impractical without forking Payload internals.
  2. pg-monitor or query logging middleware — Log-based approach with no OTel integration. Rejected: produces log entries outside the trace pipeline, losing span correlation.

See ADR-017 for the full decision rationale.