Skip to content

Add PostgreSQL query-to-trace correlation - #807

Open
pmcollins wants to merge 11 commits into
mainfrom
postgresql-application-name-trace-context-cleanup
Open

pmcollins wants to merge 11 commits into
mainfrom
postgresql-application-name-trace-context-cleanup

Conversation

@pmcollins

@pmcollins pmcollins commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds experimental, opt-in PostgreSQL query-to-trace correlation for Psycopg 3 (sync/async) and Psycopg2 (sync). Writes the database client span's W3C traceparent to application_name so Database Monitoring query samples can link to the APM trace and span.

Enable with SPLUNK_DB_TRACE_CONTEXT_PROPAGATION_ENABLED=true (disabled by default).

Reuses OpenTelemetry driver spans, applies context at driver execution, and resets application_name afterward. See docs/postgresql.md for setup, Collector requirements, and limitations.

Keep SET, query execution, and reset under the connection lock. Skip named cursors, cover cleanup failures and cancellation, and move setup and limits into dedicated documentation.

Assisted-by: Codex (GPT-6)
Use existing exception instances and contextlib.suppress. Check cancellation releases the connection by executing another query instead of reading the private lock.

Assisted-by: Codex (GPT-6)
Reuse connection lock ownership only in the same thread or task, and restore the outer span context after nested queries. Serialize transaction-control SQL without propagation commands so COMMIT stays idle and rollback cannot restore a BEGIN span. Add unit and real PostgreSQL regression coverage and document the conservative SQL exclusions.

Assisted-by: Codex (GPT-6)
Capture the upstream database span in a bounded cursor lease, then apply application_name only when customer super() calls reach the native driver. Keep auxiliary custom SQL outside the propagation lock, expire copied execution contexts, and carry the active setting through skipped nested calls.

Accept parenthesized queries and classify callproc by method role. Use native internal cursors and retain custom factories in Psycopg 3 manual instrumentation. Add unit and PostgreSQL 16 regressions for all four review findings and document the private instrumentation hooks.

Assisted-by: Codex (GPT-6)
@pmcollins
pmcollins force-pushed the postgresql-application-name-trace-context-cleanup branch from dc4edd1 to 44b07de Compare October 15, 2026 13:22
Rename the opt-in setting to SPLUNK_DB_TRACE_CONTEXT_PROPAGATION_ENABLED across runtime configuration, documentation, existing tests, and the PostgreSQL CI smoke matrix. Clarify that Python currently applies the setting only to PostgreSQL.

Assisted-by: Codex (GPT-6)
Exercise automatic CLI startup, manual instrumentation, and disabled propagation with real PostgreSQL and the oteltest OTLP receiver. Match query application_name values to received database client span IDs and retain the existing database regressions in a shared helper.

Update the PostgreSQL CI matrix, add callback failure checks, and document local execution. Make failed applications and missing or mismatched exports fail the runner explicitly.

Assisted-by: Codex (GPT-6)
@pmcollins pmcollins changed the title Add experimental PostgreSQL query-to-trace correlation Add PostgreSQL query-to-trace correlation Oct 15, 2026
@pmcollins
pmcollins marked this pull request as ready for review October 15, 2026 19:19
@pmcollins
pmcollins requested review from a team as code owners October 15, 2026 19:19
pmcollins and others added 4 commits October 19, 2026 14:54
Split activation and driver adapter construction into focused helpers. Inline signature forwarding helpers and clarify Psycopg names. Extract active query context management and application_name execution cleanup for both sync and async paths.

Assisted-by: Codex (GPT-6)
Normalize correlation commands in query statistics, skip propagation in pipelines, and handle Python 3.14 templates without converting bound values to text. Add regressions and simplify the setup documentation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants