opentelemetry-instrumentation-dbapi: instrument commit and rollback

[bmwalters]

Description

Adds instrumentation for database commit() and rollback() transaction operations across all DB-API instrumentations.

Supersedes #4519, which superseded #3964. Prior review discussion is on #4519.

Type of change

• New feature (non-breaking change which adds functionality)

Changes

• Add commit() and rollback() span instrumentation to dbapi.
• Add enable_transaction_spans configuration flag (experimental; default False).
• Add AsyncTracedConnectionProxy for async connections (psycopg).
• Plumb the flag through dependent instrumentors: pymysql, mysql, mysqlclient, psycopg, psycopg2, sqlite3, pymssql.
• Spans use the post-DB semantic convention stability migration for DB-API and 7 inheriting db client instrumentors #4109 semconv stability helpers, so OTEL_SEMCONV_STABILITY_OPT_IN selects old / new / dup attribute names.
• On failure the SDK records the exception and sets span status to ERROR; error.type is added under new DB semconv.

How Has This Been Tested?

• Unit tests in test_dbapi_integration.py for sync commit/rollback, parameterized across default / database / database/dup semconv modes
• Unit tests in test_psycopg_integration.py for sync and async commit/rollback
• Functional tests for pymysql in test_pymysql_functional.py

Exported trace example

From a fresh clone, with sqlcommenter fully on and enable_transaction_spans=True (the new opt-in):

git clone -b sql-transactions https://github.com/bmwalters/opentelemetry-python-contrib.git
cd opentelemetry-python-contrib
uv sync --frozen --all-packages

cat > /tmp/demo.py <<'PY'
import sqlite3
from opentelemetry import trace
from opentelemetry.instrumentation.dbapi import wrap_connect
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

# wrap_connect (not the SQLite3Instrumentor) is used so the full sqlcommenter
# config plumbs through; the instrumentor doesn't expose those kwargs.
wrap_connect(
    "demo", sqlite3, "connect", "sqlite",
    enable_commenter=True,
    enable_attribute_commenter=True,
    enable_transaction_spans=True,
)

conn = sqlite3.connect(":memory:")
cur = conn.cursor()
cur.execute("CREATE TABLE t (x INTEGER)")
cur.execute("INSERT INTO t VALUES (1)")
conn.commit()
cur.execute("INSERT INTO t VALUES (2)")
conn.rollback()
conn.close()
# Failure: commit on a closed connection raises ProgrammingError
try:
    conn.commit()
except Exception:
    pass
PY

uv run python /tmp/demo.py

Default semconv mode:

{
  "name": "INSERT",
  "kind": "SpanKind.CLIENT",
  "attributes": {
    "db.system": "sqlite",
    "db.statement": "INSERT INTO t VALUES (1) /*db_driver='sqlite3%%3Aunknown',dbapi_level='2.0',dbapi_threadsafety=3,driver_paramstyle='qmark',traceparent='00-5f7bc80c598cfab29da35b2a3028e582-bf7b4514b5d50195-03'*/"
  }
}
{
  "name": "COMMIT",
  "kind": "SpanKind.CLIENT",
  "attributes": {
    "db.system": "sqlite",
    "db.operation": "COMMIT"
  }
}
{
  "name": "ROLLBACK",
  "kind": "SpanKind.CLIENT",
  "attributes": {
    "db.system": "sqlite",
    "db.operation": "ROLLBACK"
  }
}

Under OTEL_SEMCONV_STABILITY_OPT_IN=database, all spans use the new attribute names; failed operations additionally carry error.type. Example failed COMMIT:

{
  "name": "COMMIT",
  "kind": "SpanKind.CLIENT",
  "status": {
    "status_code": "ERROR",
    "description": "ProgrammingError: Cannot operate on a closed database."
  },
  "attributes": {
    "db.system.name": "sqlite",
    "db.operation.name": "COMMIT",
    "error.type": "ProgrammingError"
  },
  "events": [
    {
      "name": "exception",
      "attributes": {
        "exception.type": "sqlite3.ProgrammingError",
        "exception.message": "Cannot operate on a closed database.",
        "exception.escaped": "False"
      }
    }
  ]
}

Does This PR Require a Core Repo Change?

• Yes. - Link to PR:
• No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

• Followed the style guidelines of this project
• Changelogs have been updated
• Unit tests have been added
• Documentation has been updated