OpenTelemetry mysqlclient Instrumentation

The integration with MySQLClient supports the MySQLClient library and can be enabled by using MySQLClientInstrumentor.

Usage

import MySQLdb
from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor

MySQLClientInstrumentor().instrument()

cnx = MySQLdb.connect(database="MySQL_Database")
cursor = cnx.cursor()
cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)")
cursor.execute("INSERT INTO test (testField) VALUES (123)")
cnx.commit()
cursor.close()
cnx.close()

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 MySQLdb
from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor

MySQLClientInstrumentor().instrument(enable_commenter=True)

cnx = MySQLdb.connect(database="MySQL_Database")
cursor = cnx.cursor()
cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)")
cursor.execute("INSERT INTO test (testField) VALUES (123)")
cnx.commit()
cursor.close()
cnx.close()

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 MySQLdb
from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor

# Opts into sqlcomment for MySQLClient trace integration.
# Opts out of tags for mysql_client_version, db_driver.
MySQLClientInstrumentor().instrument(
    enable_commenter=True,
    commenter_options={
        "mysql_client_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 (URL encoded).	`MySQLdb%%%%3A1.2.3`
`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'`
`mysql_client_version`	MySQL client version.	`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.

from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor

# Opts into sqlcomment for mysqlclient trace integration.
# Opts into sqlcomment for `db.statement` and/or `db.query.text` span attribute.
MySQLClientInstrumentor().instrument(
    enable_commenter=True,
    enable_attribute_commenter=True,
)

Warning

Capture of sqlcomment in db.statement/db.query.text may have high cardinality without platform normalization. See Semantic Conventions for database spans for more information.

API

class opentelemetry.instrumentation.mysqlclient.MySQLClientInstrumentor(*args, **kwargs)[source]

Bases: BaseInstrumentor

instrumentation_dependencies()[source]

Return a list of python packages with versions that the will be instrumented.

The format should be the same as used in requirements.txt or pyproject.toml.

For example, if an instrumentation instruments requests 1.x, this method should look like: :rtype: Collection[str]

def instrumentation_dependencies(self) -> Collection[str]:
return [‘requests ~= 1.0’]

This will ensure that the instrumentation will only be used when the specified library is present in the environment.

static instrument_connection(connection, tracer_provider=None, enable_commenter=None, commenter_options=None, enable_attribute_commenter=None)[source]

Enable instrumentation in a mysqlclient connection.

Parameters:

connection – The MySQL connection instance to instrument. This connection is typically created using MySQLdb.connect() and needs to be wrapped to collect telemetry.
tracer_provider – A custom TracerProvider instance to be used for tracing. If not specified, the globally configured tracer provider will be used.
enable_commenter – A flag to enable the OpenTelemetry SQLCommenter feature. If set to True, SQL queries will be enriched with contextual information (e.g., database client details). Default is None.
commenter_options –
A dictionary of configuration options for SQLCommenter. All options are enabled (True) by default. This allows you to customize metadata appended to queries. Possible options include:
- db_driver: Adds the database driver name and version.
- dbapi_threadsafety: Adds threadsafety information.
- dbapi_level: Adds the DB-API version.
- mysql_client_version: Adds the MySQL client version.
- driver_paramstyle: Adds the parameter style.
- opentelemetry_values: Includes traceparent values.

Returns:

An instrumented MySQL connection with OpenTelemetry support enabled.

static uninstrument_connection(connection)[source]

Disable instrumentation in a mysqlclient connection.

Parameters:: connection – The connection to uninstrument.
Returns:: An uninstrumented connection.