OpenTelemetry MySQL Instrumentation
MySQL instrumentation supporting mysql-connector, it can be enabled by
using MySQLInstrumentor.
Usage
import mysql.connector
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
# Call instrument() to wrap all database connections
MySQLInstrumentor().instrument()
cnx = mysql.connector.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)")
cursor.close()
cnx.close()
import mysql.connector
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
# Alternatively, use instrument_connection for an individual connection
cnx = mysql.connector.connect(database="MySQL_Database")
instrumented_cnx = MySQLInstrumentor().instrument_connection(cnx)
cursor = instrumented_cnx.cursor()
cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)")
cursor.execute("INSERT INTO test (testField) VALUES (123)")
cursor.close()
instrumented_cnx.close()
SQLCOMMENTER
You can optionally configure mysql-connector instrumentation to enable sqlcommenter which enriches the query with contextual information.
Usage
import mysql.connector
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
MySQLInstrumentor().instrument(enable_commenter=True, commenter_options={})
cnx = mysql.connector.connect(database="MySQL_Database")
cursor = cnx.cursor()
cursor.execute("INSERT INTO test (testField) VALUES (123)")
cursor.close()
cnx.close()
For example,
Invoking cursor.execute("INSERT INTO test (testField) VALUES (123)") will lead to sql query "INSERT INTO test (testField) VALUES (123)" but when SQLCommenter is enabled
the query will get appended with some configurable tags like "INSERT INTO test (testField) VALUES (123) /*tag=value*/;"
WARNING: sqlcommenter for mysql-connector instrumentation should NOT be used if your application initializes cursors with prepared=True, which will natively prepare and execute MySQL statements. Adding sqlcommenting will introduce a severe performance penalty by repeating Prepare of statements by mysql-connector that are made unique by traceparent in sqlcomment. The penalty does not happen if cursor prepared=False (default) and instrumentor enable_commenter=True.
SQLCommenter Configurations
We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword
db_driver = True(Default) or False
For example, :: Enabling this flag will add mysql.connector and its version, e.g. /mysql.connector%%3A1.2.3/
dbapi_threadsafety = True(Default) or False
For example, :: Enabling this flag will add threadsafety /dbapi_threadsafety=2/
dbapi_level = True(Default) or False
For example, :: Enabling this flag will add dbapi_level /dbapi_level=’2.0’/
mysql_client_version = True(Default) or False
For example, :: Enabling this flag will add mysql_client_version /mysql_client_version=’123’/
driver_paramstyle = True(Default) or False
For example, :: Enabling this flag will add driver_paramstyle /driver_paramstyle=’pyformat’/
opentelemetry_values = True(Default) or False
For example, :: Enabling this flag will add traceparent values /traceparent=’00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01’/
SQLComment in span attribute
If sqlcommenter is enabled, you can optionally configure mysql-connector instrumentation to append sqlcomment to query span attribute for convenience of your platform.
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
MySQLInstrumentor().instrument(
enable_commenter=True,
enable_attribute_commenter=True,
)
For example,
Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled
the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;" for both server query and `db.statement` span attribute.
API
- class opentelemetry.instrumentation.mysql.MySQLInstrumentor(*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.
- instrument_connection(connection, tracer_provider=None, enable_commenter=None, commenter_options=None, enable_attribute_commenter=None)[source]
Enable instrumentation in a MySQL connection.
- Parameters:
connection – The existing MySQL connection instance to instrument. This connection is typically obtained through mysql.connector.connect() and is instrumented to collect telemetry data about database interactions.
tracer_provider – An optional TracerProvider instance to use for tracing. If not provided, the globally configured tracer provider will be automatically used.
enable_commenter – Optional flag to enable/disable sqlcommenter (default False).
commenter_options – Optional configurations for tags to be appended at the sql query.
enable_attribute_commenter – Optional flag to enable/disable addition of sqlcomment to span attribute (default False). Requires enable_commenter=True.
- Returns:
An instrumented MySQL connection with OpenTelemetry tracing enabled.