OpenTelemetry Instrumentation for aiokafka

opentelemetry-instrumentation-aiokafka wraps the aiokafka async Kafka client so every message produced or consumed automatically generates an OpenTelemetry span, without changes at each call site. It registers via the standard opentelemetry_instrumentor entry point and exposes async produce and consume hooks so applications can attach custom span attributes, part of the broader OpenTelemetry Python contrib instrumentation suite maintained in the opentelemetry-python-contrib monorepo.

What You Get

• One-line AIOKafkaInstrumentor().instrument() call that patches AIOKafkaProducer and AIOKafkaConsumer to emit spans automatically
• Async produce and consume hooks (async_produce_hook, async_consume_hook) for attaching custom span attributes at send/receive time
• Standard OpenTelemetry semantic-convention attributes for Kafka messaging spans, compatible with any OTel-configured exporter/backend
• Automatic entry-point registration (opentelemetry_instrumentor) so the instrumentor can be discovered by the OpenTelemetry auto-instrumentation agent

Common Use Cases

• Tracing message flow through async Kafka producers and consumers in an asyncio microservice
• Correlating Kafka produce/consume spans with upstream HTTP or RPC spans in a distributed trace
• Attaching custom business attributes (e.g. order ID, tenant ID) to Kafka spans via the async hooks
• Feeding Kafka messaging telemetry into an existing OpenTelemetry Collector / observability backend with zero manual span code

Under The Hood

Architecture - The instrumentor lives at instrumentation/opentelemetry-instrumentation-aiokafka/src/opentelemetry/instrumentation/aiokafka/__init__.py and follows the standard OpenTelemetry Python instrumentor pattern: an AIOKafkaInstrumentor class (subclassing BaseInstrumentor) monkey-patches AIOKafkaProducer.send/send_and_wait and the consumer’s async iteration/getone methods to wrap calls in spans, with utils.py housing shared span-attribute-building logic. Tech Stack - Pure Python (requires-python >=3.10), built with hatchling, depending on opentelemetry-api, opentelemetry-instrumentation, and opentelemetry-semantic-conventions (all pinned to the monorepo’s synchronized release version), with aiokafka itself as an optional instruments extra so the base package installs without pulling in the Kafka client. Code Quality - Tests live in tests/test_instrumentation.py and tests/test_utils.py, following the same test conventions used across the ~70 other instrumentation packages in the opentelemetry-python-contrib monorepo, with shared CI, linting, and release tooling applied uniformly across all instrumentors. API Design - The API mirrors every other OpenTelemetry Python instrumentor: instrument()/uninstrument() lifecycle methods, an optional tracer_provider kwarg, and hook callables with a fixed (span, args, kwargs) (or (span, record, args, kwargs) for consume) signature — this consistency across the whole instrumentation family lowers the learning curve for anyone who has used another OTel Python instrumentor before.