{"id":2648,"library":"opentelemetry-instrumentation-tortoiseorm","title":"OpenTelemetry Instrumentation for Tortoise ORM","description":"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.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-tortoiseorm","tags":["opentelemetry","tracing","observability","orm","database","tortoiseorm","auto-instrumentation"],"install":[{"cmd":"pip install opentelemetry-instrumentation-tortoiseorm opentelemetry-sdk","lang":"bash","label":"Install instrumentation and SDK"},{"cmd":"pip install tortoise-orm","lang":"bash","label":"Install Tortoise ORM"}],"dependencies":[{"reason":"Required for the instrumentation to function, specifically versions >=0.17.0,<0.21.0 are officially supported by current instrumentation.","package":"tortoise-orm","optional":false},{"reason":"Provides the OpenTelemetry SDK components (e.g., TracerProvider, SpanProcessor, Exporter) necessary to process and export traces.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"TortoiseORMInstrumentor","correct":"from opentelemetry.instrumentation.tortoiseorm import TortoiseORMInstrumentor"}],"quickstart":{"code":"import os\nimport asyncio\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.tortoiseorm import TortoiseORMInstrumentor\n\n# 1. Setup OpenTelemetry TracerProvider and Exporter\nresource = Resource.create({\"service.name\": \"tortoise-orm-app\"})\nprovider = TracerProvider(resource=resource)\n# Using ConsoleSpanExporter for demonstration; replace with OTLPSpanExporter for real apps\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\n# 2. Instrument Tortoise ORM\nTortoiseORMInstrumentor().instrument()\n\n# 3. Tortoise ORM application code\nfrom tortoise import models, fields, Tortoise\n\nclass User(models.Model):\n    id = fields.IntField(pk=True)\n    name = fields.CharField(max_length=255)\n\n    class Meta:\n        table = \"users\"\n\n    def __str__(self):\n        return self.name\n\nasync def main():\n    # Connect to the database and generate schema\n    await Tortoise.init(db_url=\"sqlite://:memory:\", modules={\"models\": [\"__main__\"]})\n    await Tortoise.generate_schemas()\n\n    # Perform some ORM operations within a custom span to see the full flow\n    tracer = trace.get_tracer(__name__)\n    with tracer.start_as_current_span(\"application-flow\"):\n        with tracer.start_as_current_span(\"create_user\"):\n            user = await User.create(name=\"Alice\")\n            print(f\"Created user: {user.name}\")\n\n        with tracer.start_as_current_span(\"fetch_user\"):\n            fetched_user = await User.get(id=user.id)\n            print(f\"Fetched user: {fetched_user.name}\")\n\n        with tracer.start_as_current_span(\"update_user\"):\n            fetched_user.name = \"Alicia\"\n            await fetched_user.save()\n            print(f\"Updated user to: {fetched_user.name}\")\n\n        with tracer.start_as_current_span(\"delete_user\"):\n            await fetched_user.delete()\n            print(f\"Deleted user: {fetched_user.name}\")\n\n    # Close connection\n    await Tortoise.close_connections()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Monitor `opentelemetry-python-contrib` release notes for breaking changes before upgrading, especially across significant version bumps.","message":"This 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.","severity":"gotcha","affected_versions":"All `0.x.x` beta versions"},{"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'`).","message":"The `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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Always include `TortoiseORMInstrumentor().instrument()` early in your application's lifecycle, typically before any database connections are established or queries are executed.","message":"Forgetting to call `TortoiseORMInstrumentor().instrument()` will result in no Tortoise ORM operations being traced. This instrumentation is not automatically enabled by simply importing the package.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The 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`).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}