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:

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+aiosqlite:///:memory:")
SQLAlchemyInstrumentor().instrument(
    engine=engine.sync_engine
)

Configuration

SQLCommenter

You can optionally enable sqlcommenter which enriches the query with contextual information. Queries made after setting up trace integration with sqlcommenter enabled will have configurable key-value pairs appended to them, e.g. "select * from auth_users; /*traceparent=00-01234567-abcd-01*/". This supports context propagation between database client and server when database log records are enabled. For more information, see:

• Semantic Conventions - Database Spans

• sqlcommenter

from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor

SQLAlchemyInstrumentor().instrument(enable_commenter=True)

SQLCommenter with commenter_options

The key-value pairs appended to the query can be configured using commenter_options. When sqlcommenter is enabled, all available KVs/tags are calculated by default. commenter_options supports opting out of specific KVs.

from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor

# Opts into sqlcomment for SQLAlchemy trace integration.
# Opts out of tags for db_driver, db_framework.
SQLAlchemyInstrumentor().instrument(
    enable_commenter=True,
    commenter_options={
        "db_driver": False,
        "db_framework": False,
    }
)

Available commenter_options

The following sqlcomment key-values can be opted out of through commenter_options:

Commenter Option	Description	Example
db_driver	Database driver name.	db_driver='psycopg2'
db_framework	Database framework name with version.	db_framework='sqlalchemy:1.4.0'
opentelemetry_values	OpenTelemetry context as traceparent at time of query.	traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'

SQLComment in span attribute

If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in the query span db.statement and/or db.query.text attribute for your needs. If commenter_options have been set, the span attribute comment will also be configured by this setting.

from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor

# Opts into sqlcomment for SQLAlchemy trace integration.
# Opts into sqlcomment for `db.statement` and/or `db.query.text` span attribute.
SQLAlchemyInstrumentor().instrument(
    enable_commenter=True,
    commenter_options={},
    enable_attribute_commenter=True,
)

Warning

Capture of sqlcomment in db.statement/db.query.text may have high cardinality without platform normalization. See Semantic Conventions for database spans for more information.

API

class opentelemetry.instrumentation.sqlalchemy.SQLAlchemyInstrumentor(*args, **kwargs)

Bases: BaseInstrumentor

An instrumentor for SQLAlchemy See BaseInstrumentor

instrumentation_dependencies()

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.