diff --git a/.chloggen/postgresql-application-name-propagation.yaml b/.chloggen/postgresql-application-name-propagation.yaml new file mode 100644 index 0000000000..547fb07f82 --- /dev/null +++ b/.chloggen/postgresql-application-name-propagation.yaml @@ -0,0 +1,5 @@ +change_type: enhancement +component: db +note: Add context propagation for PostgreSQL via `SET application_name`. +issues: [2162] +subtext: diff --git a/docs/db/postgresql.md b/docs/db/postgresql.md index 13229bdb06..9a554cd711 100644 --- a/docs/db/postgresql.md +++ b/docs/db/postgresql.md @@ -9,6 +9,8 @@ linkTitle: PostgreSQL - [Spans](#spans) +- [Context propagation](#context-propagation) + - [SET application_name](#set-application_name) - [Metrics](#metrics) @@ -165,6 +167,36 @@ and SHOULD be provided **at span creation time** (if provided at all): +## Context propagation + +**Status**: [Development][DocumentStatus] + +### SET application_name + +Instrumentations MAY propagate context using [`SET application_name`](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-APPLICATION-NAME) by injecting fixed-length part of span context (trace-id, span-id, trace-flags, protocol version) before executing a query. For example, when using W3C Trace Context, only a string representation of [`traceparent`](https://www.w3.org/TR/trace-context/#traceparent-header) SHOULD be injected. Context injection SHOULD NOT be enabled by default, but instrumentation MAY allow users to opt into it. + +Variable context parts (`tracestate`, `baggage`) SHOULD NOT be injected since `application_name` value length (63 characters in a standard build) is limited to less than [`NAMEDATALEN`](https://www.postgresql.org/docs/current/runtime-config-preset.html#GUC-MAX-IDENTIFIER-LENGTH) characters . + +Instrumentations that propagate context MUST execute `SET application_name` on the same physical connection as the SQL statement. + +The `application_name` value is visible in [`pg_stat_activity`](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) and can be included in PostgreSQL server logs via `%a` in [`log_line_prefix`](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-LINE-PREFIX). + +Example: + +For a query `SELECT * FROM songs` where `traceparent` is `00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01`: + +Run the following command on the same physical connection as the SQL statement: + +```sql +SET application_name = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'; +``` + +Then run the query: + +```sql +SELECT * FROM songs; +``` + ## Metrics PostgreSQL client instrumentations SHOULD collect metrics according to the general