{"id":8381,"library":"opentelemetry-instrumentation-pymssql","title":"OpenTelemetry pymssql Instrumentation","description":"This library provides OpenTelemetry instrumentation for `pymssql`, a Python wrapper for FreeTDS that enables interaction with Microsoft SQL Server. It automatically creates spans for database connection and query operations, helping to trace SQL interactions within your application. The current version is 0.62b0, and it's released as part of the `opentelemetry-python-contrib` project, which has a frequent release cadence.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","observability","tracing","mssql","sql server","database","pymssql"],"install":[{"cmd":"pip install opentelemetry-instrumentation-pymssql pymssql","lang":"bash","label":"Install instrumentation and pymssql"}],"dependencies":[{"reason":"The database driver being instrumented. Must be installed separately.","package":"pymssql","optional":false},{"reason":"Core OpenTelemetry API for defining tracing concepts.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry SDK for processing and exporting telemetry data.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"PymssqlInstrumentor","correct":"from opentelemetry.instrumentation.pymssql import PymssqlInstrumentor"}],"quickstart":{"code":"import os\nimport pymssql\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.pymssql import PymssqlInstrumentor\n\n# 1. Configure OpenTelemetry Tracer Provider\nresource = Resource.create({\"service.name\": \"pymssql-example\"})\nprovider = TracerProvider(resource=resource)\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument pymssql\nPymssqlInstrumentor().instrument()\n\n# 3. Use pymssql normally\n# Replace with your actual MSSQL connection details or use environment variables\nserver = os.environ.get(\"MSSQL_SERVER\", \"your_server.database.windows.net\")\nuser = os.environ.get(\"MSSQL_USER\", \"your_username\")\npassword = os.environ.get(\"MSSQL_PASSWORD\", \"your_password\")\ndatabase = os.environ.get(\"MSSQL_DATABASE\", \"your_database\")\n\nif not all([server, user, password, database]):\n    print(\"WARNING: Skipping pymssql connection as environment variables for MSSQL_SERVER, MSSQL_USER, MSSQL_PASSWORD, MSSQL_DATABASE are not set.\")\n    print(\"Please set these to run the quickstart.\")\nelse:\n    print(f\"Attempting to connect to MSSQL: {server}/{database} with user {user}...\")\n    try:\n        with pymssql.connect(server, user, password, database) as conn:\n            with conn.cursor() as cursor:\n                cursor.execute('SELECT 1 as result')\n                row = cursor.fetchone()\n                print(f\"Query result: {row}\")\n        print(\"pymssql connection and query successful (and instrumented!). Check console for OTel traces.\")\n    except Exception as e:\n        print(f\"Error connecting to or querying MSSQL: {e}\")\n        print(\"Ensure MSSQL server is accessible and credentials are correct.\")","lang":"python","description":"This quickstart demonstrates how to set up OpenTelemetry with `pymssql` instrumentation. It configures a basic `TracerProvider` with a `ConsoleSpanExporter`, instruments `pymssql`, and then performs a sample database connection and query. Remember to replace placeholder credentials or set corresponding environment variables for a runnable example."},"warnings":[{"fix":"Review release notes for each update and test thoroughly, especially if upgrading across minor beta versions.","message":"This instrumentation is in 'beta' (indicated by 'b' in version number, e.g., 0.62b0). While functional, its API or behavior might undergo minor changes in future releases before reaching a stable version.","severity":"gotcha","affected_versions":"All versions below 1.0.0"},{"fix":"Ensure `pip install pymssql` is run in your environment before attempting to use the instrumentation.","message":"The `pymssql` library itself must be installed separately from `opentelemetry-instrumentation-pymssql`. The instrumentation package does not automatically install `pymssql` as a dependency.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Call `PymssqlInstrumentor().instrument()` once during application startup, typically after OpenTelemetry SDK configuration.","message":"Instrumentation occurs globally: calling `PymssqlInstrumentor().instrument()` will patch all subsequent `pymssql` connections and queries within the current process. Ensure this is done early in your application's lifecycle.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the quickstart example and OpenTelemetry documentation for setting up a `TracerProvider` and `SpanExporter`.","message":"For traces to be visible, you must correctly configure a `TracerProvider` and add a `SpanProcessor` with an appropriate `SpanExporter` (e.g., `ConsoleSpanExporter`, `OTLPSpanExporter`). Without this setup, instrumentation will run, but no telemetry data will be emitted.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `pymssql` using pip: `pip install pymssql`.","cause":"The `pymssql` library is not installed in your Python environment. The OpenTelemetry instrumentation requires the target library to be present.","error":"ModuleNotFoundError: No module named 'pymssql'"},{"fix":"Ensure `trace.set_tracer_provider(provider)` is called and your `provider` has at least one `SpanProcessor` with a working `SpanExporter` attached.","cause":"OpenTelemetry SDK (TracerProvider, SpanProcessor, SpanExporter) is not correctly configured or set. Instrumentation generates spans, but without an exporter, they are not processed or sent anywhere.","error":"No traces appear in the console or backend, even after calling `instrument()`."}]}