OpenTelemetry#
Advanced Alchemy looks up SQLAlchemy’s create_engine and create_async_engine each time it creates an engine. OpenTelemetry’s SQLAlchemy instrumentation therefore traces the engines Advanced Alchemy creates with its default factories, including each engine in a routing configuration, without an Advanced Alchemy setting.
Installation#
uv add opentelemetry-sdk opentelemetry-instrumentation-sqlalchemy
pip install opentelemetry-sdk opentelemetry-instrumentation-sqlalchemy
pdm add opentelemetry-sdk opentelemetry-instrumentation-sqlalchemy
poetry add opentelemetry-sdk opentelemetry-instrumentation-sqlalchemy
Enabling Tracing#
Call SQLAlchemyInstrumentor().instrument() once before the first engine is created. For standalone configs and Litestar, calling it before app startup works because engines are created during lifespan startup. For FastAPI, Starlette, Flask, and Sanic, call it before attaching AdvancedAlchemy(config, app) or calling init_app(app), which creates engines eagerly:
from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
from advanced_alchemy.config import SQLAlchemyAsyncConfig
SQLAlchemyInstrumentor().instrument()
config = SQLAlchemyAsyncConfig(connection_string="postgresql+asyncpg://user:pass@localhost/db")
Queries on those engines are then traced. Which spans are recorded and exported depends on the OpenTelemetry SDK configuration (tracer provider, exporter, sampling), which your application sets up; Advanced Alchemy does not.
Note
Advanced Alchemy does not add an OpenTelemetry dependency, so installs and tests across Python 3.9–3.15 and SQLAlchemy 2.0/2.1 are unaffected. Each opentelemetry-instrumentation-sqlalchemy release enforces its own Python and SQLAlchemy version bounds; for example, 0.66b2 requires Python 3.10 or later and SQLAlchemy earlier than 2.1. On an unsupported SQLAlchemy version, instrument() logs a version conflict and skips tracing gracefully without breaking engine creation.
Engines Created Elsewhere#
instrument() traces engines created through SQLAlchemy’s factories after it runs. It does not trace:
an engine created before that call, such as one passed as
engine_instanceor throughsession_configbind/bindsengines owned by a custom
session_makerengines returned by a custom
create_engine_callablethat keeps its own reference to the factory
Calls to instrument() are ignored while the instrumentor is already active, so pass existing engines to the first call. Async engines need their sync_engine:
SQLAlchemyInstrumentor().instrument(engines=[engine.sync_engine])
This covers engines that already exist. Engines that a custom factory creates later through its own reference to the factory cannot be added afterwards.