OpenCensus SQLAlchemy Integration

0.1.3 verified Fri May 01 auth: no python

OpenCensus SQLAlchemy Integration provides tracing instrumentation for SQLAlchemy queries. It wraps SQLAlchemy engine events to capture spans for each executed query, including bind parameters and execution time. Version 0.1.3 is current, with irregular releases.

pip install opencensus-ext-sqlalchemy

Common errors

error ValueError: not enough values to unpack (expected 2, got 0) ↓

cause Triggered when SQLAlchemyTrace wraps an engine that has not been fully initialized or is a null pool.

fix

Ensure the engine is created normally (e.g., sqlite:///:memory:) and that no custom event listeners interfere.

error AttributeError: module 'opencensus.ext.sqlalchemy' has no attribute 'trace' ↓

cause Incorrect import path; the module is actually 'opencensus.ext.sqlalchemy.trace'.

fix

Change import to: from opencensus.ext.sqlalchemy.trace import SQLAlchemyTrace

Warnings

gotcha SQLAlchemyTrace must wrap the engine before any queries are executed. Instrumentation after connections have been created will not capture traces for those connections. ↓

fix Apply SQLAlchemyTrace immediately after engine creation, before first use.

gotcha The package does not automatically export traces; you must configure an exporter (e.g., Azure Monitor, Zipkin) via OpenCensus tracing. Without an exporter, no data is sent anywhere. ↓

fix Set up OpenCensus tracing with an exporter, e.g., 'from opencensus.trace import tracer as tracer_module' and configure with a sampler and exporter.

deprecated OpenCensus Python is in maintenance mode and no longer actively developed. Google recommends using OpenTelemetry instead. However, the extension still works for existing users. ↓

fix Migrate to OpenTelemetry with opentelemetry-instrumentation-sqlalchemy.

Imports

SQLAlchemyTrace

from opencensus.ext.sqlalchemy.trace import SQLAlchemyTrace

Quickstart

Instrument a SQLAlchemy engine to trace queries.

import os
from opencensus.ext.sqlalchemy.trace import SQLAlchemyTrace
from sqlalchemy import create_engine

# Create engine
engine = create_engine('sqlite:///:memory:')

# Instrument with OpenCensus tracer
tracer = SQLAlchemyTrace(engine)

# Now every query executed via this engine will be traced
with engine.connect() as conn:
    conn.execute("SELECT 1")