Registry / observability / opentelemetry-instrumentation-tortoiseorm

opentelemetry-instrumentation-tortoiseorm

JSON →
library0.65b0pypypi✓ verified 23d ago

This library provides automatic OpenTelemetry tracing for applications using the Tortoise ORM. It captures database operations (e.g., SELECT, INSERT, UPDATE, DELETE) as spans, enriching them with relevant attributes like query text, table names, and latency. The current version is 0.62b0 and it's part of the `opentelemetry-python-contrib` project, which has a rapid, often weekly, release cadence for beta components.

pip install opentelemetry-instrumentation-tortoiseorm opentelemetry-sdk
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-tortoiseorm
observabilitypythonv0.65b0
Install
2.5s avg
Import
Disk
47MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 72.8MB
glibc
py 3.103.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.
fix
Monitor `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.
fix
Ensure 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.
fix
Always 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`).
fix
Ensure 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.
Agent activity
14 hits · last 30 days
node
10
OpenAI (training)
2
Resources
opentelemetry-instrumentation-tortoiseorm — pip install opentelemetry-instrumentation-tortoiseorm · libregistry