OpenTelemetry pymssql Instrumentation

Common errors

• ModuleNotFoundError: No module named 'pymssql'

  cause The `pymssql` library is not installed in your Python environment. The OpenTelemetry instrumentation requires the target library to be present.
  fix Install `pymssql` using pip: `pip install pymssql`.

• No traces appear in the console or backend, even after calling `instrument()`.

  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.
  fix Ensure `trace.set_tracer_provider(provider)` is called and your `provider` has at least one `SpanProcessor` with a working `SpanExporter` attached.

Warnings

• gotcha 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.
  Fix: Review release notes for each update and test thoroughly, especially if upgrading across minor beta versions.
• gotcha The `pymssql` library itself must be installed separately from `opentelemetry-instrumentation-pymssql`. The instrumentation package does not automatically install `pymssql` as a dependency.
  Fix: Ensure `pip install pymssql` is run in your environment before attempting to use the instrumentation.
• gotcha 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.
  Fix: Call `PymssqlInstrumentor().instrument()` once during application startup, typically after OpenTelemetry SDK configuration.
• gotcha 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.
  Fix: Refer to the quickstart example and OpenTelemetry documentation for setting up a `TracerProvider` and `SpanExporter`.

Install

• pip install opentelemetry-instrumentation-pymssql pymssql Install instrumentation and pymssql

Imports

• PymssqlInstrumentor

  from opentelemetry.instrumentation.pymssql import PymssqlInstrumentor

Quickstart

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.

import os
import pymssql
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.pymssql import PymssqlInstrumentor

# 1. Configure OpenTelemetry Tracer Provider
resource = Resource.create({"service.name": "pymssql-example"})
provider = TracerProvider(resource=resource)
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 2. Instrument pymssql
PymssqlInstrumentor().instrument()

# 3. Use pymssql normally
# Replace with your actual MSSQL connection details or use environment variables
server = os.environ.get("MSSQL_SERVER", "your_server.database.windows.net")
user = os.environ.get("MSSQL_USER", "your_username")
password = os.environ.get("MSSQL_PASSWORD", "your_password")
database = os.environ.get("MSSQL_DATABASE", "your_database")

if not all([server, user, password, database]):
    print("WARNING: Skipping pymssql connection as environment variables for MSSQL_SERVER, MSSQL_USER, MSSQL_PASSWORD, MSSQL_DATABASE are not set.")
    print("Please set these to run the quickstart.")
else:
    print(f"Attempting to connect to MSSQL: {server}/{database} with user {user}...")
    try:
        with pymssql.connect(server, user, password, database) as conn:
            with conn.cursor() as cursor:
                cursor.execute('SELECT 1 as result')
                row = cursor.fetchone()
                print(f"Query result: {row}")
        print("pymssql connection and query successful (and instrumented!). Check console for OTel traces.")
    except Exception as e:
        print(f"Error connecting to or querying MSSQL: {e}")
        print("Ensure MSSQL server is accessible and credentials are correct.")