open-telemetry / open-telemetry/opentelemetry-python-contrib
`opentelemetry-instrumentation-sqlalchemy`: 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
sqlalchemy uses its own EngineTracer and does not capture query parameters
at all today, even though it already uses the semconv stability mechanism.
SQLAlchemy exposes the bound parameters of a statement through its event
system (e.g. the before_cursor_execute hook receives parameters /
executemany).
What to do
- Add a
capture_parametersoption to the sqlalchemy instrumentor (off by
default, since parameter values may be sensitive). - When enabled, emit
db.query.parameter.<key>under the new semconv using the
shared_set_db_query_parametershelper from
opentelemetry.instrumentation._semconv.- Key named parameters (dict) by name and positional parameters (sequence) by
0-based index.
- Key named parameters (dict) by name and positional parameters (sequence) by
- Do not capture parameters when SQLAlchemy reports the execution as
executemany(batch). - Follow the migration rule: new attribute under the new semconv only. If a
legacydb.statement.parametersbehavior is added for the old semconv, keep
it behind_report_old; otherwise emitting only the new attribute under the
new semconv is acceptable since there is nothing to preserve.
Acceptance criteria
- A user can enable parameter capture via
capture_parameters. - New semconv:
db.query.parameter.<key>emitted with the correct keys. - Batch (
executemany) executions do not emitdb.query.parameter.*. - Values captured as strings.
Tests
- Cover positional and named parameters, and the batch case.
- Verify exact attribute names and string value types against the spec.
- Test against the oldest and latest supported SQLAlchemy versions.
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 SQLAlchemy instrumentor's EngineTracer and its before_cursor_execute event, then read the shared _set_db_query_parameters helper in opentelemetry.instrumentation._semconv. Add coverage for named, positional, and executemany parameters across the oldest and latest supported SQLAlchemy versions. Done means opt-in string-valued db.query.parameter. attributes use correct keys and are absent for batches.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, sqlalchemy
- Domain
- databases
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100