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("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("INSERT INTO test (testField) VALUES (123)"
instrumented_cnx.commit()
cursor.close()
instrumented_cnx.close()
SQLCOMMENTER
You can optionally configure PyMySQL instrumentation to enable sqlcommenter which enriches the query with contextual information.
Usage
import pymysql
from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
PyMySQLInstrumentor().instrument(enable_commenter=True, commenter_options={})
cnx = pymysql.connect(database="MySQL_Database")
cursor = cnx.cursor()
cursor.execute("INSERT INTO test (testField) VALUES (123)"
cnx.commit()
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*/;"
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 pymysql and its version, e.g. /pymysql%%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 PyMySQL instrumentation to append sqlcomment to query span attribute for convenience of your platform.
from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
PyMySQLInstrumentor().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.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.