open-telemetry / open-telemetry/opentelemetry-python-contrib
`opentelemetry-instrumentation-dbapi`: capture `db.query.parameter.<key>`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 1.1k
- Avg merge
- 4d 15h
- Merged PRs (30d)
- 16
Description
Part of #4787 (global db.query.parameter.<key> tracking issue).
Background
dbapi is the shared base used by most SQL instrumentations (psycopg, psycopg2,
mysql, mysqlclient, pymysql, pymssql, sqlite3). Today CursorTracer._populate_span
captures parameters as a single non-standard db.statement.parameters blob when
capture_parameters=True, in all semconv modes and even on batch operations.
This sub-issue is foundational: it also adds the shared helper the other
sub-issues reuse.
What to do
- Add a shared helper
_set_db_query_parameters(result, parameters, sem_conv_opt_in_mode)
inopentelemetry.instrumentation._semconvthat:- only emits under the new database semconv (
_report_new); - keys named parameters (mapping) by name and positional parameters
(sequence) by 0-based index; - treats
str/bytesas a single scalar (does not iterate characters); - stringifies each value, capturing falsy values too (
0,False,""); - uses the
DB_QUERY_PARAMETER_TEMPLATEconstant from the semconv package
(no hardcoded strings).
- only emits under the new database semconv (
- In
CursorTracer._populate_span, whencapture_parametersis enabled:- emit
db.statement.parametersonly under the old semconv (_report_old); - emit
db.query.parameter.<key>under the new semconv via the helper; - skip
db.query.parameter.<key>for batch operations (executemany),
detected from the wrapped cursor method.
- emit
Acceptance criteria
- Default (old) semconv:
db.statement.parametersunchanged; no
db.query.parameter.*. database(stable) semconv:db.query.parameter.<key>emitted; no
db.statement.parameters.database/dupsemconv: both present.- Positional params keyed by index, named params keyed by name, values are
strings. executemanynever emitsdb.query.parameter.*.
Tests
- Unit tests for the helper (positional, named, string-value type, scalar
string,None, old-mode no-op). - Integration tests in
test_dbapi_integration.pyfor old / new / dup modes,
named parameters and the batch-suppression case.
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.
Research direction
Start with the shared helper in opentelemetry.instrumentation._semconv and CursorTracer._populate_span, then read the semconv package constants and the existing tests. Run the helper unit tests and test_dbapi_integration.py for old, new, duplicate, named-parameter, and executemany cases. Done means the acceptance criteria hold across all semconv modes, including batch suppression.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, sql
- Domain
- databases, observability
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 62/100