{"id":3192,"library":"opentelemetry-instrumentation-aio-pika","title":"OpenTelemetry Aio-pika Instrumentation","description":"This library, part of the OpenTelemetry Python Contrib project, provides automatic instrumentation for `aio-pika` to trace RabbitMQ applications. It helps in generating telemetry data like traces and spans for operations involving `aio-pika` message publishing and consuming. The current version is `0.62b0`, and it's actively developed as part of the broader OpenTelemetry Python ecosystem.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","instrumentation","rabbitmq","amqp","aio-pika","observability","tracing","async"],"install":[{"cmd":"pip install opentelemetry-instrumentation-aio-pika","lang":"bash","label":"Install library"}],"dependencies":[{"reason":"The library being instrumented. Compatible with versions >= 7.2.0, < 10.0.0.","package":"aio-pika","optional":false},{"reason":"Core OpenTelemetry API for Python.","package":"opentelemetry-api","optional":false},{"reason":"Core OpenTelemetry SDK for Python.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"AioPikaInstrumentor","correct":"from opentelemetry.instrumentation.aio_pika import AioPikaInstrumentor"}],"quickstart":{"code":"import asyncio\nfrom aio_pika import Message, connect\nfrom opentelemetry.instrumentation.aio_pika import AioPikaInstrumentor\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\n\n# Configure OpenTelemetry TracerProvider\nresource = Resource.create({\"service.name\": \"aio-pika-example\"})\ntracer_provider = TracerProvider(resource=resource)\ntracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(tracer_provider)\n\n# Instrument aio-pika\nAioPikaInstrumentor().instrument()\n\nasync def main() -> None:\n    print(\"Connecting to RabbitMQ... (Ensure RabbitMQ is running, e.g., docker run -p 5672:5672 rabbitmq)\")\n    connection = await connect(\"amqp://guest:guest@localhost/\")\n    async with connection:\n        channel = await connection.channel()\n        queue = await channel.declare_queue(\"hello\")\n\n        # Publish a message\n        print(\"Publishing message...\")\n        await channel.default_exchange.publish(\n            Message(b\"Hello World!\"),\n            routing_key=queue.name\n        )\n        print(\"Message published.\")\n\n        # Basic consume example (for demonstration, a real consumer would run longer)\n        print(\"Consuming message...\")\n        async with queue.iterator() as queue_iter:\n            async for message in queue_iter:\n                async with message.process():\n                    print(f\"Received message: {message.body.decode()}\")\n                    break # Stop after one message for this quickstart\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to instrument `aio-pika` to trace message publishing and consuming. It sets up a basic OpenTelemetry TracerProvider to export traces to the console and then instruments `aio-pika` globally. It requires a running RabbitMQ instance, which can be started with `docker run -p 5672:5672 rabbitmq`."},"warnings":[{"fix":"Upgrade `opentelemetry-instrumentation-aio-pika` to a version compatible with `aio-pika` 9.x (e.g., current versions like 0.62b0 support `aio-pika >= 7.2.0, < 10.0.0`).","message":"Older versions of `opentelemetry-instrumentation-aio-pika` are incompatible with `aio-pika` versions 9.1+. A refactoring in `aio-pika` 9.1 changed `channel.connection` to `channel._connection`, leading to `AttributeError` in unpatched instrumentation.","severity":"breaking","affected_versions":"<0.60b0 (approx.)"},{"fix":"Monitor release notes for breaking changes, especially during major OpenTelemetry Python Contrib updates. Pin major versions to control upgrades.","message":"The instrumentation is currently in beta (`0.62b0`). While generally stable, minor breaking changes to the API or semantic conventions, especially for in-development signals, may occur before a stable `1.0.0` release.","severity":"gotcha","affected_versions":"All beta versions (`0.x.y.bZ`)"},{"fix":"If metrics are required for `aio-pika` activities, manual instrumentation or an external metrics collection approach will be necessary.","message":"This instrumentation currently provides tracing (spans) but does NOT provide metrics for `aio-pika` operations.","severity":"gotcha","affected_versions":"All versions up to 0.62b0"},{"fix":"Explicitly manage context within your async message handlers using `opentelemetry.context.attach()` and `opentelemetry.context.detach()`, or use `opentelemetry.trace.set_current_span()` if creating new spans manually, to ensure proper parent-child relationships.","message":"In complex asynchronous message consumption scenarios with `aio-pika`, especially when message processing involves further asynchronous tasks or handlers that detach from the original consumer callback, OpenTelemetry context propagation might be lost. This can result in broken traces where child spans are not linked to the originating message consumption span.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}