Registry /
observability / opentelemetry-instrumentation-mysql
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 22.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.6s · import 0.000s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MySQLInstrumentor
✓ from opentelemetry.instrumentation.mysql import MySQLInstrumentor
✗ from opentelemetry.instrumentation.mysql import MySQLInstrumentor
This quickstart demonstrates how to enable OpenTelemetry MySQL instrumentation and perform basic database operations. It sets up a simple `TracerProvider` with a `ConsoleSpanExporter` to print traces to the console. You must have `mysql-connector-python` installed and a running MySQL server with the specified connection details (or environment variables) for the example to work.
import os
import mysql.connector
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
# 1. Configure OpenTelemetry SDK
resource = Resource.create({"service.name": "mysql-instrumentation-example"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Enable MySQL instrumentation
MySQLInstrumentor().instrument()
# 3. Use mysql.connector as usual
# Replace with your actual MySQL connection details
# For a runnable example, you might need a local MySQL server or Docker setup
# Environment variables are used for security and flexibility
DB_HOST = os.environ.get('MYSQL_HOST', 'localhost')
DB_USER = os.environ.get('MYSQL_USER', 'root')
DB_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'password')
DB_NAME = os.environ.get('MYSQL_DATABASE', 'testdb')
try:
# Establish a connection
conn = mysql.connector.connect(
host=DB_HOST,
user=DB_USER,
password=DB_PASSWORD,
database=DB_NAME
)
cursor = conn.cursor()
# Example: Create a table
cursor.execute("DROP TABLE IF EXISTS test_table")
cursor.execute("CREATE TABLE test_table (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))")
# Example: Insert data
cursor.execute("INSERT INTO test_table (name) VALUES (%s)", ("Alice",))
conn.commit()
# Example: Select data
cursor.execute("SELECT * FROM test_table")
result = cursor.fetchall()
print(f"Query Result: {result}")
cursor.close()
conn.close()
print("MySQL operations completed and traces should be visible in console.")
except mysql.connector.Error as err:
print(f"MySQL Error: {err}")
print("Please ensure MySQL server is running and connection details are correct. You might need to install mysql-connector-python (pip install mysql-connector-python).")
finally:
# Ensure the provider is shut down to export any remaining spans
provider.shutdown()
Debug
Known issues
gotchaEnabling SQLCommenter (via `enable_commenter=True` in `instrument()`) with MySQL cursors initialized with `prepared=True` can severely degrade performance. This is because SQLCommenter makes statements unique, forcing the database to re-prepare them.fixAvoid using `enable_commenter=True` when your application uses `prepared=True` cursors. If SQLCommenter is needed, ensure cursors are not using prepared statements (default is `False`).
affects: All versions
deprecatedMySQL Connector/Python versions 8.1.0 through 8.4.0 included an `[opentelemetry]` extra for `pip install`. Using this extra was not recommended as it installed bundled OpenTelemetry SDK/API libraries, which could lead to dependency conflicts or unexpected behavior with other OpenTelemetry components.fixAlways install `opentelemetry-instrumentation-mysql` and its required OpenTelemetry SDK components separately and explicitly, rather than relying on bundled versions from `mysql-connector-python` extras.
affects: mysql-connector-python 8.1.0 - 8.4.0
gotchaOpenTelemetry semantic conventions, which define attribute names and structures, can evolve. While efforts are made to ensure backward compatibility, changes in semantic conventions might affect existing dashboards or alerts. New versions might require setting the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable to emit both old and stable semantic conventions during a migration period.fixKeep your OpenTelemetry SDK and instrumentation packages updated. Consult the OpenTelemetry Python documentation and release notes for semantic convention changes. During migrations, use `OTEL_SEMCONV_STABILITY_OPT_IN=http/dup,database/dup` (or similar) to ensure both old and new attributes are emitted.
affects: All versions (general OpenTelemetry behavior)
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
mysql-connector-pythonrequiredThis instrumentation targets the `mysql-connector-python` library. It must be installed separately to enable database tracing.