feat: replace db.statement.parameters with db.query.parameter.<key> per OTel semconv

[Lotram]

Summary

Replace the non-standard db.statement.parameters span attribute with individual db.query.parameter.<key> attributes, following the OpenTelemetry database semantic conventions.

Before

A single attribute containing the stringified tuple of all parameters:

db.statement.parameters = "('param1Value', False)"

After

Individual attributes, one per parameter:

db.query.parameter.0 = "'param1Value'"
db.query.parameter.1 = "False"

For dict-style parameters (named placeholders, dbapi only):

db.query.parameter.name = "'John'"
db.query.parameter.id = "42"

Motivation

The db.statement.parameters attribute was a non-standard, implementation-specific choice. The OTel semantic conventions define db.query.parameter.<key> as individual per-parameter attributes with string values. This change aligns the instrumentation with that specification.

Design choices

Inline logic per instrumentation (no shared helper)

Each instrumentation knows the shape of its parameters:

• dbapi: tuple/list (positional) or dict (named) per PEP 249 — needs both indexed and named key handling
• asyncpg: always a tuple (positional *args) — simple indexed loop
• tortoiseorm: always a tuple of lists (from args[1:]) — simple indexed loop

Since the logic is a simple for-loop in each case, it's inlined at each call site rather than abstracted into a shared utility function.

repr() instead of str() for parameter values

The old code used str(args[1]) on the entire tuple, which internally calls repr() on each element (that's how tuple.__str__ works). To preserve the same per-element representation — and to avoid ambiguity between e.g. the string "42" and the integer 42 — we use repr() on individual values. This means strings appear quoted ('param1Value') while numbers and booleans appear unquoted (42, False).

DB_QUERY_PARAMETER_TEMPLATE constant

Uses the existing DB_QUERY_PARAMETER_TEMPLATE constant from opentelemetry.semconv._incubating.attributes.db_attributes (value: "db.query.parameter") rather than hardcoding the string, following the pattern used throughout the repo.

tortoiseorm: parameters grouped under a single key

The tortoiseorm instrumentation wraps tortoise DB client methods (e.g. execute_insert(query, values)). The existing code passes args[1:] (all arguments after the query) as the parameters value. This results in all query values being grouped under db.query.parameter.0 as a single repr'd list (e.g. "['Alice', 'Engineer']"), rather than one attribute per parameter.

We chose not to change this behavior in this PR (e.g. by unwrapping args[1] instead of args[1:]) because the tortoise client methods have varying signatures across backends and operation types (execute_insert, execute_many, execute_query, execute_script), and we lack sufficient understanding of the ORM internals to safely flatten the parameters in all cases. This can be improved in a follow-up.

Changes

1. opentelemetry-instrumentation-dbapi: Replaced db.statement.parameters with inline db.query.parameter.<key> logic in TracedCursor._populate_span; handles both positional (tuple/list) and named (dict) parameters; updated docstrings and tests (dbapi, aiopg, psycopg)
2. opentelemetry-instrumentation-asyncpg: Replaced db.statement.parameters with inline indexed loop in _hydrate_span_from_args; updated docker functional tests
3. opentelemetry-instrumentation-tortoiseorm: Replaced db.statement.parameters with inline indexed loop; added tests for multiple parameters and no parameters
4. CHANGELOG: Breaking change + Added entry

Breaking change

Consumers that relied on the db.statement.parameters attribute will need to switch to reading individual db.query.parameter.<key> attributes. This affects all DB instrumentations that support capture_parameters=True.

Unlike the db.statement → db.query.text migration (which uses OTEL_SEMCONV_STABILITY_OPT_IN for a gradual transition), we don't provide a dual-emit feature flag here. db.statement.parameters was never part of the OTel semantic conventions — it was a custom, non-standard attribute. A clean break is more appropriate than a transition period that would legitimize the old format.

Related PRs

• #4109 — DB semantic convention stability migration for DB-API (and 7 inheriting instrumentors). That PR migrates db.statement → db.query.text, db.name → db.namespace, etc. via the OTEL_SEMCONV_STABILITY_OPT_IN mechanism using the existing _semconv.py helpers. Our PR is complementary: it handles the db.statement.parameters → db.query.parameter.<key> migration, which DB semantic convention stability migration for DB-API and 7 inheriting db client instrumentors open-telemetry/opentelemetry-python-contrib#4109 does not cover. The two PRs will conflict on the same dbapi files and should be coordinated. Note that db.query.parameter.<key> is already the new semconv name, so it does not need the old/new dual-emit pattern.

Follow-ups

• db.statement → db.query.text: The OTel semantic conventions also deprecate db.statement in favor of db.query.text. PR #4109 handles this for dbapi and its dependents. asyncpg and tortoiseorm still need the same migration.
• tortoiseorm parameter flattening: Unwrap args[1] instead of args[1:] to emit one attribute per parameter instead of a single grouped list (see design choices above).

[gregoiredx]

this should probably not be in opentelemetry/instrumentation/utils.py it's very dbapi related, here we are in the utils common to all instrumentations

[gregoiredx]

I would keep it simple and

Suggested change

	span_attributes.update(db_query_parameter_attributes(parameters))
	span_attributes["db.statement.parameters"] = str(parameters)
	for key, value in enumerate(parameters):
	attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{key}"] = repr(value)

[gregoiredx]

I would try to avoid breaking change and make the new attribute optional

[gregoiredx]

This is asyncpg, that's not where we want the feature!

https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py

[Lotram]

I simply wanted the change to be propagated everywhere

[Lotram]

Closing for now, as db.operation.parameter.key is not stable yet