OpenTelemetry PyMySQL Instrumentation

Warnings

• gotcha The `opentelemetry-instrumentation-pymysql` package only provides the instrumentation. You must explicitly install `pymysql` yourself, as it is a peer dependency.
  Fix: Ensure `pymysql` is installed: `pip install pymysql`.
• gotcha OpenTelemetry instrumentations require the OpenTelemetry SDK (TracerProvider, SpanProcessor, Exporter) to be configured *before* the instrumentor is enabled, otherwise no traces will be generated or exported. This is a common oversight.
  Fix: Configure `trace.set_tracer_provider()` and `add_span_processor()` with an appropriate exporter (e.g., `ConsoleSpanExporter`, `OTLPSpanExporter`) before calling `PyMySQLInstrumentor().enable()`.
• deprecated As of OpenTelemetry Python SDK 1.0.0, manual calls to `set_tracer_provider` and `set_meter_provider` are generally discouraged in favor of `opentelemetry-sdk-extension-aws`'s `AwsLambdaInstrumentor` for serverless environments. For general applications, consider using environment variables (e.g., `OTEL_TRACER_PROVIDER`) or `opentelemetry-sdk-extension-auto`.
  Fix: While `set_tracer_provider` still works, for more robust and production-ready setups, especially in serverless or containerized environments, consider using automatic instrumentation or environment variables. This specific PyMySQL instrumentation is typically enabled manually via `PyMySQLInstrumentor().enable()`.
• gotcha The package version `0.62b0` indicates a beta release. While generally stable, minor API changes or behavioral adjustments might occur in future beta or stable releases of the `opentelemetry-python-contrib` repository.
  Fix: Periodically check the official OpenTelemetry Python Contrib GitHub repository and documentation for updates and release notes, especially when upgrading between beta versions.

Install

• pip install opentelemetry-instrumentation-pymysql Install instrumentation
• pip install pymysql Install PyMySQL (required)

Imports

• PyMySQLInstrumentor

  from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor

Quickstart

This quickstart demonstrates how to set up the OpenTelemetry Python SDK and enable PyMySQL instrumentation. It configures a simple ConsoleSpanExporter to print traces to the console. When `PyMySQLInstrumentor().enable()` is called, subsequent `pymysql` operations will automatically generate spans. Remember to replace placeholder database credentials with actual ones for a functional setup.

import os
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.pymysql import PyMySQLInstrumentor
import pymysql

# 1. Configure OpenTelemetry SDK
resource = Resource.create({"service.name": "pymysql-example"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# 2. Enable PyMySQL Instrumentation
PyMySQLInstrumentor().enable()

# 3. Use PyMySQL (this will be traced)
# For a real application, replace with actual database credentials
try:
    # Use os.environ.get for sensitive info or mock connection
    conn = pymysql.connect(
        host=os.environ.get('MYSQL_HOST', 'localhost'),
        user=os.environ.get('MYSQL_USER', 'root'),
        password=os.environ.get('MYSQL_PASSWORD', 'testpass'),
        database=os.environ.get('MYSQL_DATABASE', 'testdb')
    )
    cursor = conn.cursor()
    cursor.execute("SELECT 1 + 1")
    result = cursor.fetchone()
    print(f"PyMySQL query result: {result}")
    cursor.close()
    conn.close()
except Exception as e:
    print(f"Could not connect to PyMySQL or execute query: {e}")
    print("Make sure a MySQL/MariaDB server is running and accessible with correct credentials.")

print("Traces should be printed to console above.")