[db] Add context propagation for PostgreSQL via SET application_name#3581
[db] Add context propagation for PostgreSQL via SET application_name#3581mhennoch wants to merge 7 commits into
Conversation
Co-authored-by: Sam Xie <sam@samxie.me>
…tions into pg-set-app-name
|
This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days. |
There was a problem hiding this comment.
This is a good step forward. Even if we later decide that application_name is not the ideal long-term propagation mechanism, having a documented convention now is useful: it gives instrumentation authors something interoperable to implement, helps users immediately, and can also inform a future redesign if we later standardize a better carrier or protocol-level approach.
|
@open-telemetry/semconv-db-approvers, can you take a look as well? |
lmolkova
moved this from Untriaged
to Awaiting codeowners approval
in Semantic Conventions Triage
|
This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days. |
There was a problem hiding this comment.
Pull request overview
Adds a PostgreSQL-specific context propagation mechanism to the database semantic conventions by specifying how to inject W3C Trace Context via the session-scoped application_name setting.
Changes:
- Document PostgreSQL context propagation using
SET application_namewithtraceparent. - Add a changelog entry for the new PostgreSQL context propagation guidance.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/db/postgresql.md | Adds a new “Context propagation” section describing SET application_name usage and examples. |
| .chloggen/postgresql-application-name-propagation.yaml | Adds a release note entry for the PostgreSQL context propagation addition. |
| Instrumentations MAY propagate W3C Trace Context using [`SET application_name`](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-APPLICATION-NAME) by setting `application_name` to the string representation of [`traceparent`](https://www.w3.org/TR/trace-context/#traceparent-header) before executing a query. The value MUST NOT include any prefix, suffix, or wrapper. Context injection SHOULD NOT be enabled by default, but instrumentation MAY allow users to opt into it. | ||
|
|
||
| Other context values (`tracestate`, `baggage`) MUST NOT be injected because `application_name` is limited to less than [`NAMEDATALEN`](https://www.postgresql.org/docs/current/runtime-config-preset.html#GUC-MAX-IDENTIFIER-LENGTH) characters (63 characters in a standard build). | ||
|
|
||
| Because `application_name` is session-scoped, instrumentations SHOULD update it before every propagated query on the same physical connection as the query. Instrumentations MAY clear or restore it after query execution. Users should be aware that while enabled, this mechanism may overwrite connection-level `application_name` values between queries. |
|
This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days. |
|
This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days. |
Add context propagation for PostgreSQL via SET application_name
Part of #2162
Adds SET application_name as a context propagation mechanism for PostgreSQL, following the pattern established for SQL Server (SET CONTEXT_INFO) and Oracle (V$SESSION.ACTION).
Why SET application_name?
PostgreSQL instrumentation already supports SQL Commenter, but it has limitations:
SET application_name operates at the session level and avoids all of these issues. The value is visible in pg_stat_activity and the OpenTelemetry Collector PostgreSQL receiver already parses it to extract trace context from query samples.
Note on application_name
There is ongoing discussion about whether application_name is the ideal long-term mechanism — a protocol-level approach would be better but doesn't exist today. An imperfect convention behind an opt-in flag is still useful: it unblocks users now and can help motivate database-native solutions over time.
Existing implementations