Registry /
observability / opentelemetry-instrumentation-tortoiseorm
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 72.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.5s · import 0.000s · 24MB
47MB installed
● package 47MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TortoiseORMInstrumentor
✓ from opentelemetry.instrumentation.tortoiseorm import TortoiseORMInstrumentor
This quickstart demonstrates how to set up OpenTelemetry tracing for Tortoise ORM. It initializes the OpenTelemetry TracerProvider and uses the ConsoleSpanExporter to print traces to the console. The `TortoiseORMInstrumentor().instrument()` call enables the automatic tracing. A simple Tortoise ORM model and asynchronous CRUD operations are performed, which will generate database-related spans.
import os
import asyncio
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.tortoiseorm import TortoiseORMInstrumentor
# 1. Setup OpenTelemetry TracerProvider and Exporter
resource = Resource.create({"service.name": "tortoise-orm-app"})
provider = TracerProvider(resource=resource)
# Using ConsoleSpanExporter for demonstration; replace with OTLPSpanExporter for real apps
processor = SimpleSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 2. Instrument Tortoise ORM
TortoiseORMInstrumentor().instrument()
# 3. Tortoise ORM application code
from tortoise import models, fields, Tortoise
class User(models.Model):
id = fields.IntField(pk=True)
name = fields.CharField(max_length=255)
class Meta:
table = "users"
def __str__(self):
return self.name
async def main():
# Connect to the database and generate schema
await Tortoise.init(db_url="sqlite://:memory:", modules={"models": ["__main__"]})
await Tortoise.generate_schemas()
# Perform some ORM operations within a custom span to see the full flow
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("application-flow"):
with tracer.start_as_current_span("create_user"):
user = await User.create(name="Alice")
print(f"Created user: {user.name}")
with tracer.start_as_current_span("fetch_user"):
fetched_user = await User.get(id=user.id)
print(f"Fetched user: {fetched_user.name}")
with tracer.start_as_current_span("update_user"):
fetched_user.name = "Alicia"
await fetched_user.save()
print(f"Updated user to: {fetched_user.name}")
with tracer.start_as_current_span("delete_user"):
await fetched_user.delete()
print(f"Deleted user: {fetched_user.name}")
# Close connection
await Tortoise.close_connections()
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
gotchaThis instrumentation (version 0.62b0) is in beta. While generally stable, API surfaces or captured attributes may change in future minor or major releases without strict backward compatibility guarantees.fixMonitor `opentelemetry-python-contrib` release notes for breaking changes before upgrading, especially across significant version bumps.
affects: All `0.x.x` beta versions
breakingThe `opentelemetry-instrumentation-tortoiseorm` package has specific version compatibility requirements for `tortoise-orm`. Current versions expect `tortoise-orm>=0.17.0,<0.21.0`. Using an unsupported version might lead to uninstrumented queries or runtime errors.fixEnsure your `tortoise-orm` version falls within the range specified in the instrumentation's `pyproject.toml` or `setup.py` (e.g., `pip install 'tortoise-orm>=0.17.0,<0.21.0'`).
affects: All versions
gotchaForgetting to call `TortoiseORMInstrumentor().instrument()` will result in no Tortoise ORM operations being traced. This instrumentation is not automatically enabled by simply importing the package.fixAlways include `TortoiseORMInstrumentor().instrument()` early in your application's lifecycle, typically before any database connections are established or queries are executed.
affects: All versions
gotchaThe instrumentation itself only generates spans; to actually view or export these traces, you must configure an OpenTelemetry `TracerProvider` with appropriate `SpanProcessor` and `SpanExporter` (e.g., `OTLPSpanExporter`, `ConsoleSpanExporter`).fixEnsure your application initializes a `TracerProvider`, adds at least one `SpanProcessor`, and sets the provider via `trace.set_tracer_provider()` before starting the application logic.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
tortoise-ormrequiredRequired for the instrumentation to function, specifically versions >=0.17.0,<0.21.0 are officially supported by current instrumentation.
opentelemetry-sdkrequiredProvides the OpenTelemetry SDK components (e.g., TracerProvider, SpanProcessor, Exporter) necessary to process and export traces.