open-telemetry / open-telemetry/opentelemetry-python-contrib
Implement `db.query.parameter.<key>` across database instrumentations
@ocelotl is already working on this.
Since Aug 4, 2026.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 1.1k
- Avg merge
- 4d 15h
- Merged PRs (30d)
- 16
Description
Summary
The database semantic conventions,
and in particular db.query.parameter.<key>,
are implemented in very few of our database instrumentations, and where
parameters are captured today it is done with a non-standard attribute.
Prepared statement parameter values are important for end users debugging
queries, and we should support them consistently across the board.
This is a tracking issue. The actual work is split into one sub-issue per
package so each can be reviewed, merged and reverted independently (one PR per
sub-issue). This issue is closed once all sub-issues are closed.
Background
Grepping the repo for db.query.parameter / DB_QUERY_PARAMETER returns
nothing — no instrumentation emits the standard attribute. The instrumentations
that capture parameters at all use a custom, non-spec attribute
db.statement.parameters, a single stringified blob of the whole parameter
sequence.
Problems with the current behavior:
db.statement.parametersis not a semantic convention attribute. The
spec-defined attribute isdb.query.parameter.<key>, one attribute per
parameter.- Named vs. positional parameters are not distinguished. Named parameters
should be keyed by name (db.query.parameter.userName), positional
parameters by 0-based index (db.query.parameter.0). - The legacy blob is emitted in all semconv modes, including the new/stable
database semconv where it does not belong. - Parameters are captured even on batch operations (
executemany), which the
spec says they SHOULD NOT be.
Target behavior
Every in-scope instrumentation should, when parameter capture is opted in:
- Emit one
db.query.parameter.<key>attribute per parameter — keyed by name
for named parameters and by 0-based index for positional parameters, values
captured as strings. - Keep parameter capture behind an opt-in (values may contain sensitive data).
- Emit
db.query.parameter.<key>only under the new/stable database semconv.
Keepdb.statement.parametersfor the old semconv (both underdatabase/dup)
so existing users are not broken during the migration. - Not capture parameters on batch operations (
executemany).
The shared dbapi base and a small helper in
opentelemetry.instrumentation._semconv do the bulk of the work and are reused
by every SQL instrumentation.
Scope
In scope: SQL / prepared-statement instrumentations. Out of scope: NoSQL /
command-based instrumentations where db.query.parameter does not apply
(redis, pymongo, cassandra).
psycopg and psycopg2 need no dedicated work: they already expose
capture_parameters and inherit the dbapi base, so the base sub-issue covers
them. Adding an explicit test for the new attribute at their level is optional.
Sub-issues
- #4788 —
opentelemetry-instrumentation-dbapi: shared helper + dbapi base (foundational) - #4789 —
opentelemetry-instrumentation-mysql: exposecapture_parameters - #4790 —
opentelemetry-instrumentation-mysqlclient: exposecapture_parameters - #4791 —
opentelemetry-instrumentation-pymysql: exposecapture_parameters - #4792 —
opentelemetry-instrumentation-pymssql: exposecapture_parameters - #4793 —
opentelemetry-instrumentation-sqlite3: exposecapture_parameters - #4794 —
opentelemetry-instrumentation-asyncpg: replace legacy blob withdb.query.parameter.<key> - #4795 —
opentelemetry-instrumentation-tortoiseorm: replace legacy blob withdb.query.parameter.<key> - #4796 —
opentelemetry-instrumentation-aiopg: implementdb.query.parameter.<key> - #4797 —
opentelemetry-instrumentation-sqlalchemy: implementdb.query.parameter.<key>
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.