OpenTelemetry DBAPI Instrumentation

Warnings

• breaking OpenTelemetry Python contrib packages, including `opentelemetry-instrumentation-dbapi`, are often in beta (indicated by `b0` suffix). This means API changes and breaking modifications can occur between minor versions without strict adherence to semantic versioning until a stable `1.0.0` release. Semantic conventions, which define attribute names and structures, also evolve and may require updates to instrumentation configurations. For example, the `db.statement` attribute's inclusion of sqlcomment became opt-in in previous versions.
  Fix: Regularly review the `opentelemetry-python-contrib` CHANGELOG for specific instrumentation packages and adapt your code to new APIs or semantic conventions. Pin major versions in `requirements.txt`.
• gotcha Incorrectly identifying the `connect` method name for your DBAPI driver is a common mistake. For instance, `pyodbc`'s connection function is `connect`, not `Connection`. Using the wrong method name will result in instrumentation failing silently or partially.
  Fix: Always verify the exact name of the connection function for your specific DBAPI driver by checking its documentation or source code. Use the correct string in the `trace_integration` or `wrap_connect` call.
• gotcha The `sqlcommenter` feature, which enriches SQL queries with OpenTelemetry context for better database-side observability, is disabled by default. If not explicitly enabled, trace context will not be appended to SQL queries, hindering end-to-end trace correlation if the database logs are consumed by an observability backend.
  Fix: Enable `sqlcommenter` by setting `enable_commenter=True` in the `trace_integration` or `wrap_connect` call: `trace_integration(module, 'connect', 'database_system', enable_commenter=True)`. Further configuration can be done via `commenter_options`.
• gotcha When using pre-forking servers (e.g., Gunicorn with multiple workers), OpenTelemetry automatic instrumentation, especially for metrics, can lead to inconsistencies. The forking process can create issues with background threads and locks in SDK components like `PeriodicExportingMetricReader`, potentially causing missing or incorrect metrics.
  Fix: Consider deploying with a single worker for metrics, or explore programmatic instrumentation specifically for metrics in a multi-worker setup. Alternatively, use workarounds like Prometheus with direct OTLP export, as detailed in OpenTelemetry Python troubleshooting guides.
• gotcha In some older versions (e.g., `0.53b1`), the `opentelemetry-instrumentation-dbapi` might not correctly respect the `suppress_instrumentation` context manager. This can lead to spans being generated even when you intend to suppress them.
  Fix: Ensure you are using a recent version of `opentelemetry-instrumentation-dbapi` where this issue has been addressed. As of `0.61b0`, this should be resolved. If upgrading is not an option, verify generated spans thoroughly and apply alternative suppression logic if necessary.

Install

• pip install opentelemetry-instrumentation-dbapi opentelemetry-sdk mysql-connector-python Install with a sample DBAPI driver

Imports

• trace_integration

  from opentelemetry.instrumentation.dbapi import trace_integration

  The DbApiInstrumentor class is not directly exposed or the primary way to enable instrumentation; 'trace_integration' and 'wrap_connect' are the public functions.

Quickstart

This quickstart demonstrates how to set up the OpenTelemetry Python SDK with a `ConsoleSpanExporter` and then apply `opentelemetry-instrumentation-dbapi` to `mysql.connector`. It traces database operations, including connection, table creation, insertion, and selection, ensuring that these actions generate spans visible in the console. Environment variables are used for database credentials for a runnable example.

import os
import mysql.connector
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.dbapi import trace_integration

# Configure OpenTelemetry SDK
resource = {"service.name": os.environ.get('OTEL_SERVICE_NAME', 'dbapi-example')}
tracer_provider = TracerProvider.from_resource_attributes(resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# Get a tracer
tracer = trace.get_tracer(__name__)

# Instrument the database connector (e.g., mysql.connector)
# Pass the module, the name of its connect method, and the database system identifier
trace_integration(mysql.connector, "connect", "mysql")

try:
    # Establish a connection using the instrumented module
    connection = mysql.connector.connect(
        host=os.environ.get('MYSQL_HOST', 'localhost'),
        user=os.environ.get('MYSQL_USER', 'root'),
        password=os.environ.get('MYSQL_PASSWORD', 'password'),
        database=os.environ.get('MYSQL_DATABASE', 'testdb')
    )

    with tracer.start_as_current_span("db-operations"):
        cursor = connection.cursor()
        cursor.execute("CREATE TABLE IF NOT EXISTS users (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))")
        cursor.execute("INSERT INTO users (name) VALUES ('Alice')")
        connection.commit()
        cursor.execute("SELECT * FROM users")
        result = cursor.fetchall()
        print(f"Fetched result: {result}")
        cursor.close()

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if 'connection' in locals() and connection.is_connected():
        connection.close()
    print("Application finished.")