open-telemetry / open-telemetry/opentelemetry-python-contrib

Implement `db.query.parameter.<key>` across database instrumentations

Open
#4,787 1 comment 0 reactions 1 assignee View on GitHub

@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:

  1. db.statement.parameters is not a semantic convention attribute. The
    spec-defined attribute is db.query.parameter.<key>, one attribute per
    parameter.
  2. 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).
  3. The legacy blob is emitted in all semconv modes, including the new/stable
    database semconv where it does not belong.
  4. 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.
    Keep db.statement.parameters for the old semconv (both under database/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: expose capture_parameters
  • #4790 — opentelemetry-instrumentation-mysqlclient: expose capture_parameters
  • #4791 — opentelemetry-instrumentation-pymysql: expose capture_parameters
  • #4792 — opentelemetry-instrumentation-pymssql: expose capture_parameters
  • #4793 — opentelemetry-instrumentation-sqlite3: expose capture_parameters
  • #4794 — opentelemetry-instrumentation-asyncpg: replace legacy blob with db.query.parameter.<key>
  • #4795 — opentelemetry-instrumentation-tortoiseorm: replace legacy blob with db.query.parameter.<key>
  • #4796 — opentelemetry-instrumentation-aiopg: implement db.query.parameter.<key>
  • #4797 — opentelemetry-instrumentation-sqlalchemy: implement db.query.parameter.<key>

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.