OpenTelemetry PyMySQL Instrumentation
The integration with PyMySQL supports the PyMySQL library and can be enabled
by using PyMySQLInstrumentor.
Usage
import pymysql
from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
# Call instrument() to wrap all database connections
PyMySQLInstrumentor().instrument()
cnx = pymysql.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()
import pymysql
from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
# Alternatively, use instrument_connection for an individual connection
cnx = pymysql.connect(database="MySQL_Database")
instrumented_cnx = PyMySQLInstrumentor().instrument_connection(
cnx,
enable_commenter=True,
commenter_options={
"db_driver": True,
"mysql_client_version": True
}
)
cursor = instrumented_cnx.cursor()
cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)")
cursor.execute("INSERT INTO test (testField) VALUES (123)")
instrumented_cnx.commit()
cursor.close()
instrumented_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 pymysql
from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
PyMySQLInstrumentor().instrument(enable_commenter=True)
cnx = pymysql.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 pymysql
from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
# Opts into sqlcomment for PyMySQL trace integration.
# Opts out of tags for mysql_client_version, db_driver.
PyMySQLInstrumentor().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 |
|---|---|---|
|
Database driver name with version. |
|
|
DB-API threadsafety value: 0-3 or unknown. |
|
|
DB-API API level: 1.0, 2.0, or unknown. |
|
|
DB-API paramstyle for SQL statement parameter. |
|
|
MySQL client version. |
|
|
OpenTelemetry context as traceparent at time of query. |
|
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.pymysql import PyMySQLInstrumentor
# Opts into sqlcomment for PyMySQL trace integration.
# Opts into sqlcomment for `db.statement` span attribute.
PyMySQLInstrumentor().instrument(
enable_commenter=True,
enable_attribute_commenter=True,
)
Warning
Capture of sqlcomment in db.statement may have high cardinality without platform normalization. See Semantic Conventions for database spans for more information.
API
- class opentelemetry.instrumentation.pymysql.PyMySQLInstrumentor(*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 PyMySQL connection.
- Parameters:
connection – The existing PyMySQL connection instance that needs to be instrumented. This connection was typically created using pymysql.connect() and is wrapped with OpenTelemetry tracing.
tracer_provider – An optional TracerProvider instance that specifies which tracer provider should be used. If not provided, the globally configured OpenTelemetry tracer provider is automatically applied.
enable_commenter – A flag to enable the SQL Commenter feature. If True, query logs will be enriched with additional contextual metadata (e.g., database version, traceparent IDs, driver information).
commenter_options – A dictionary containing configuration options for the SQL Commenter feature. You can specify various options, such as enabling driver information, database version logging, traceparent propagation, and other customizable metadata enhancements. See SQLCommenter Configurations above for more information.
- Returns:
An instrumented connection.