OpenTelemetry SQLAlchemy Instrumentation

Instrument sqlalchemy to report SQL queries.

There are two options for instrumenting code. The first option is to use the opentelemetry-instrument executable which will automatically instrument your SQLAlchemy engine. The second is to programmatically enable instrumentation via the following code:

SQLCOMMENTER

You can optionally configure SQLAlchemy instrumentation to enable sqlcommenter which enriches the query with contextual information.

Usage

from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor

SQLAlchemyInstrumentor().instrument(enable_commenter=True, commenter_options={})

For example,

Invoking engine.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;"

SQLCommenter Configurations

We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword

db_driver = True(Default) or False

For example, :: Enabling this flag will add any underlying driver like psycopg2 /db_driver=’psycopg2’/

db_framework = True(Default) or False

For example, :: Enabling this flag will add db_framework and it’s version /db_framework=’sqlalchemy:0.41b0’/

opentelemetry_values = True(Default) or False

For example, :: Enabling this flag will add traceparent values /traceparent=’00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01’/

Usage

from sqlalchemy import create_engine

from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
import sqlalchemy

engine = create_engine("sqlite:///:memory:")
SQLAlchemyInstrumentor().instrument(
    engine=engine,
)

# of the async variant of SQLAlchemy

from sqlalchemy.ext.asyncio import create_async_engine

from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
import sqlalchemy

engine = create_async_engine("sqlite:///:memory:")
SQLAlchemyInstrumentor().instrument(
    engine=engine.sync_engine
)

API

class opentelemetry.instrumentation.sqlalchemy.SQLAlchemyInstrumentor(*args, **kwargs)[source]

Bases: BaseInstrumentor

An instrumentor for SQLAlchemy See BaseInstrumentor

instrumentation_dependencies()[source]

Return a list of python packages with versions that the will be instrumented.

The format should be the same as used in requirements.txt or pyproject.toml.

For example, if an instrumentation instruments requests 1.x, this method should look like: :rtype: Collection[str]

def instrumentation_dependencies(self) -> Collection[str]:
return [‘requests ~= 1.0’]

This will ensure that the instrumentation will only be used when the specified library is present in the environment.