OpenTelemetry Database API Instrumentation

The trace integration with Database API supports libraries that follow the Python Database API Specification v2.0. https://www.python.org/dev/peps/pep-0249/

Usage

The DB-API instrumentor and its utilities provide common, core functionality for database framework or object relation mapper (ORM) instrumentations. Users will typically instrument database client code with those framework/ORM-specific instrumentations, instead of directly using this DB-API integration. Features such as sqlcommenter can be configured at framework/ORM level as well. See full list at instrumentation.

If an instrumentation for your needs does not exist, then DB-API integration can be used directly as follows.

import mysql.connector
import pyodbc

from opentelemetry.instrumentation.dbapi import (
    trace_integration,
    wrap_connect,
)

# Example: mysql.connector
trace_integration(mysql.connector, "connect", "mysql")
# Example: pyodbc
trace_integration(pyodbc, "Connection", "odbc")

# Or, directly call wrap_connect for more configurability.
wrap_connect(__name__, mysql.connector, "connect", "mysql")
wrap_connect(__name__, pyodbc, "Connection", "odbc")

Configuration

SQLCommenter

You can optionally enable sqlcommenter which enriches the query with contextual information. Queries made after setting up trace integration with sqlcommenter enabled will have configurable key-value pairs appended to them, e.g. "select * from auth_users; /*traceparent=00-01234567-abcd-01*/". This supports context propagation between database client and server when database log records are enabled. For more information, see:

import mysql.connector

from opentelemetry.instrumentation.dbapi import wrap_connect


# Opts into sqlcomment for MySQL trace integration.
wrap_connect(
    __name__,
    mysql.connector,
    "connect",
    "mysql",
    enable_commenter=True,
)

SQLCommenter with commenter_options

The key-value pairs appended to the query can be configured using commenter_options. When sqlcommenter is enabled, all available KVs/tags are calculated by default. commenter_options supports opting out of specific KVs.

import mysql.connector

from opentelemetry.instrumentation.dbapi import wrap_connect


# Opts into sqlcomment for MySQL trace integration.
# Opts out of tags for libpq_version, db_driver.
wrap_connect(
    __name__,
    mysql.connector,
    "connect",
    "mysql",
    enable_commenter=True,
    commenter_options={
        "libpq_version": False,
        "db_driver": False,
    }
)

Available commenter_options

The following sqlcomment key-values can be opted out of through commenter_options:

Commenter Option	Description	Example
`db_driver`	Database driver name with version.	`mysql.connector=2.2.9`
`dbapi_threadsafety`	DB-API threadsafety value: 0-3 or unknown.	`dbapi_threadsafety=2`
`dbapi_level`	DB-API API level: 1.0, 2.0, or unknown.	`dbapi_level=2.0`
`driver_paramstyle`	DB-API paramstyle for SQL statement parameter.	`driver_paramstyle='pyformat'`
`libpq_version`	PostgreSQL libpq version (checked for PostgreSQL only).	`libpq_version=140001`
`mysql_client_version`	MySQL client version (checked for MySQL only).	`mysql_client_version='123'`
`opentelemetry_values`	OpenTelemetry context as traceparent at time of query.	`traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`

SQLComment in span attribute

If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in the query span db.statement attribute for your needs. If commenter_options have been set, the span attribute comment will also be configured by this setting.

import mysql.connector

from opentelemetry.instrumentation.dbapi import wrap_connect


# Opts into sqlcomment for MySQL trace integration.
# Opts into sqlcomment for `db.statement` span attribute.
wrap_connect(
    __name__,
    mysql.connector,
    "connect",
    "mysql",
    enable_commenter=True,
    enable_attribute_commenter=True,
)

API

opentelemetry.instrumentation.dbapi.trace_integration(connect_module, connect_method_name, database_system, connection_attributes=None, tracer_provider=None, capture_parameters=False, enable_commenter=False, db_api_integration_factory=None, enable_attribute_commenter=False, commenter_options=None)[source]

Integrate with DB API library. https://www.python.org/dev/peps/pep-0249/

Parameters:

connect_module (Callable[..., Any]) – Module name where connect method is available.
connect_method_name (str) – The connect method name.
database_system (str) – An identifier for the database management system (DBMS) product being used.
connection_attributes (Optional[dict[str, Any]]) – Attribute names for database, port, host and user in Connection object.
tracer_provider (Optional[TracerProvider]) – The opentelemetry.trace.TracerProvider to use. If omitted the current configured one is used.
capture_parameters (bool) – Configure if db.statement.parameters should be captured.
enable_commenter (bool) – Flag to enable/disable sqlcommenter.
db_api_integration_factory (Optional[type[DatabaseApiIntegration]]) – The DatabaseApiIntegration to use. If none is passed the default one is used.
enable_attribute_commenter (bool) – Flag to enable/disable sqlcomment inclusion in db.statement span attribute. Only available if enable_commenter=True.
commenter_options (Optional[dict[str, Any]]) – Configurations for tags to be appended at the sql query.

opentelemetry.instrumentation.dbapi.wrap_connect(name, connect_module, connect_method_name, database_system, connection_attributes=None, version='', tracer_provider=None, capture_parameters=False, enable_commenter=False, db_api_integration_factory=None, commenter_options=None, enable_attribute_commenter=False)[source]

Integrate with DB API library. https://www.python.org/dev/peps/pep-0249/

Parameters:

connect_module (Callable[..., Any]) – Module name where connect method is available.
connect_method_name (str) – The connect method name.
database_system (str) – An identifier for the database management system (DBMS) product being used.
connection_attributes (Optional[dict[str, Any]]) – Attribute names for database, port, host and user in Connection object.
tracer_provider (Optional[TracerProvider]) – The opentelemetry.trace.TracerProvider to use. If omitted the current configured one is used.
capture_parameters (bool) – Configure if db.statement.parameters should be captured.
enable_commenter (bool) – Flag to enable/disable sqlcommenter.
db_api_integration_factory (Optional[type[DatabaseApiIntegration]]) – The DatabaseApiIntegration to use. If none is passed the default one is used.
commenter_options (Optional[dict[str, Any]]) – Configurations for tags to be appended at the sql query.
enable_attribute_commenter (bool) – Flag to enable/disable sqlcomment inclusion in db.statement span attribute. Only available if enable_commenter=True.

opentelemetry.instrumentation.dbapi.unwrap_connect(connect_module, connect_method_name)[source]

Disable integration with DB API library. https://www.python.org/dev/peps/pep-0249/

Parameters:

connect_module (Callable[..., Any]) – Module name where the connect method is available.
connect_method_name (str) – The connect method name.

opentelemetry.instrumentation.dbapi.instrument_connection(name, connection, database_system, connection_attributes=None, version='', tracer_provider=None, capture_parameters=False, enable_commenter=False, commenter_options=None, connect_module=None, enable_attribute_commenter=False, db_api_integration_factory=None)[source]

Enable instrumentation in a database connection.

Parameters:

name (str) – The instrumentation module name.
connection (Union[TypeVar(ConnectionT), TracedConnectionProxy[TypeVar(ConnectionT)]]) – The connection to instrument.
database_system (str) – An identifier for the database management system (DBMS) product being used.
connection_attributes (Optional[dict[str, Any]]) – Attribute names for database, port, host and user in a connection object.
tracer_provider (Optional[TracerProvider]) – The opentelemetry.trace.TracerProvider to use. If omitted the current configured one is used.
capture_parameters (bool) – Configure if db.statement.parameters should be captured.
enable_commenter (bool) – Flag to enable/disable sqlcommenter.
commenter_options (Optional[dict[str, Any]]) – Configurations for tags to be appended at the sql query.
connect_module (Optional[Callable[..., Any]]) – Module name where connect method is available.
enable_attribute_commenter (bool) – Flag to enable/disable sqlcomment inclusion in db.statement span attribute. Only available if enable_commenter=True.
db_api_integration_factory (Optional[type[DatabaseApiIntegration]]) – A class or factory function to use as a replacement for DatabaseApiIntegration. Can be used to obtain connection attributes from the connect method instead of from the connection itself (as done by the pymssql intrumentor).

Return type:

TracedConnectionProxy[TypeVar(ConnectionT)]

Returns:

An instrumented connection.

opentelemetry.instrumentation.dbapi.uninstrument_connection(connection)[source]

Disable instrumentation in a database connection.

Parameters:: connection (Union[TypeVar(ConnectionT), TracedConnectionProxy[TypeVar(ConnectionT)]]) – The connection to uninstrument.
Return type:: TypeVar(ConnectionT)
Returns:: An uninstrumented connection.

class opentelemetry.instrumentation.dbapi.DatabaseApiIntegration(name, database_system, connection_attributes=None, version='', tracer_provider=None, capture_parameters=False, enable_commenter=False, commenter_options=None, connect_module=None, enable_attribute_commenter=False)[source]

Bases: object

calculate_commenter_data()[source]

Return type:: dict[str, Any]

wrapped_connection(connect_method, args, kwargs)[source]

Add object proxy to connection object.

Return type:: TracedConnectionProxy[TypeVar(ConnectionT)]

get_connection_attributes(connection)[source]

Return type:: None

class opentelemetry.instrumentation.dbapi.TracedConnectionProxy(connection, db_api_integration=None)[source]

Bases: ObjectProxy, Generic[ConnectionT]

cursor(*args, **kwargs)[source]

opentelemetry.instrumentation.dbapi.get_traced_connection_proxy(connection, db_api_integration, *args, **kwargs)[source]

Return type:: TracedConnectionProxy[TypeVar(ConnectionT)]

class opentelemetry.instrumentation.dbapi.CursorTracer(db_api_integration)[source]

Bases: Generic[CursorT]

get_operation_name(cursor, args)[source]

Return type:: str

get_statement(cursor, args)[source]

traced_execution(cursor, query_method, *args, **kwargs)[source]

async traced_execution_async(cursor, query_method, *args, **kwargs)[source]

class opentelemetry.instrumentation.dbapi.TracedCursorProxy(cursor, db_api_integration)[source]

Bases: ObjectProxy, Generic[CursorT]

execute(*args, **kwargs)[source]

executemany(*args, **kwargs)[source]

callproc(*args, **kwargs)[source]

opentelemetry.instrumentation.dbapi.get_traced_cursor_proxy(cursor, db_api_integration, *args, **kwargs)[source]

Return type:: TracedCursorProxy[TypeVar(CursorT)]