{"id":3198,"library":"opentelemetry-instrumentation-mysql","title":"OpenTelemetry MySQL Instrumentation","description":"The `opentelemetry-instrumentation-mysql` library provides automatic instrumentation for MySQL database operations in Python applications, specifically supporting the `mysql-connector-python` library. It enables the automatic collection of trace data from database interactions, allowing for observability into distributed systems. The library is part of the OpenTelemetry Python Contrib repository and is actively maintained, with releases typically aligning with the broader OpenTelemetry Python SDK and instrumentation updates. The current version is 0.62b0.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","observability","tracing","mysql","database","instrumentation","python"],"install":[{"cmd":"pip install opentelemetry-instrumentation-mysql","lang":"bash","label":"Install library"}],"dependencies":[{"reason":"This instrumentation targets the `mysql-connector-python` library. It must be installed separately to enable database tracing.","package":"mysql-connector-python","optional":false}],"imports":[{"symbol":"MySQLInstrumentor","correct":"from opentelemetry.instrumentation.mysql import MySQLInstrumentor"}],"quickstart":{"code":"import os\nimport mysql.connector\n\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.mysql import MySQLInstrumentor\n\n# 1. Configure OpenTelemetry SDK\nresource = Resource.create({\"service.name\": \"mysql-instrumentation-example\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Enable MySQL instrumentation\nMySQLInstrumentor().instrument()\n\n# 3. Use mysql.connector as usual\n# Replace with your actual MySQL connection details\n# For a runnable example, you might need a local MySQL server or Docker setup\n# Environment variables are used for security and flexibility\nDB_HOST = os.environ.get('MYSQL_HOST', 'localhost')\nDB_USER = os.environ.get('MYSQL_USER', 'root')\nDB_PASSWORD = os.environ.get('MYSQL_PASSWORD', 'password')\nDB_NAME = os.environ.get('MYSQL_DATABASE', 'testdb')\n\ntry:\n    # Establish a connection\n    conn = mysql.connector.connect(\n        host=DB_HOST,\n        user=DB_USER,\n        password=DB_PASSWORD,\n        database=DB_NAME\n    )\n    cursor = conn.cursor()\n\n    # Example: Create a table\n    cursor.execute(\"DROP TABLE IF EXISTS test_table\")\n    cursor.execute(\"CREATE TABLE test_table (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255))\")\n\n    # Example: Insert data\n    cursor.execute(\"INSERT INTO test_table (name) VALUES (%s)\", (\"Alice\",))\n    conn.commit()\n\n    # Example: Select data\n    cursor.execute(\"SELECT * FROM test_table\")\n    result = cursor.fetchall()\n    print(f\"Query Result: {result}\")\n\n    cursor.close()\n    conn.close()\n    print(\"MySQL operations completed and traces should be visible in console.\")\n\nexcept mysql.connector.Error as err:\n    print(f\"MySQL Error: {err}\")\n    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).\")\n\nfinally:\n    # Ensure the provider is shut down to export any remaining spans\n    provider.shutdown()","lang":"python","description":"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."},"warnings":[{"fix":"Avoid 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`).","message":"Enabling 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install `opentelemetry-instrumentation-mysql` and its required OpenTelemetry SDK components separately and explicitly, rather than relying on bundled versions from `mysql-connector-python` extras.","message":"MySQL 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.","severity":"deprecated","affected_versions":"mysql-connector-python 8.1.0 - 8.4.0"},{"fix":"Keep 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.","message":"OpenTelemetry 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.","severity":"gotcha","affected_versions":"All versions (general OpenTelemetry behavior)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}