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

`opentelemetry-instrumentation-dbapi`: capture `db.query.parameter.<key>`

Open
#4,788 1 comment 0 reactions 0 assignees View on GitHub

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

  1. Add a shared helper _set_db_query_parameters(result, parameters, sem_conv_opt_in_mode)
    in opentelemetry.instrumentation._semconv that:
    • 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/bytes as a single scalar (does not iterate characters);
    • stringifies each value, capturing falsy values too (0, False, "");
    • uses the DB_QUERY_PARAMETER_TEMPLATE constant from the semconv package
      (no hardcoded strings).
  2. In CursorTracer._populate_span, when capture_parameters is enabled:
    • emit db.statement.parameters only 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.

Acceptance criteria

  • Default (old) semconv: db.statement.parameters unchanged; no
    db.query.parameter.*.
  • database (stable) semconv: db.query.parameter.<key> emitted; no
    db.statement.parameters.
  • database/dup semconv: both present.
  • Positional params keyed by index, named params keyed by name, values are
    strings.
  • executemany never emits db.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.py for old / new / dup modes,
    named parameters and the batch-suppression case.

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.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.