Registry / observability / opentelemetry-instrumentation-celery

opentelemetry-instrumentation-celery

JSON →
library0.65b0pypypi✓ verified 24d ago

This library provides OpenTelemetry instrumentation for Celery, enabling comprehensive monitoring of Celery applications by automatically collecting telemetry data such as task execution times, worker performance, and error rates. It also captures distributed traces across your task pipeline. The current version is `0.61b0`, and packages within the `opentelemetry-python-contrib` repository typically follow a monthly release cadence for beta versions.

pip install opentelemetry-instrumentation-celery opentelemetry-sdk
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-celery
observabilitypythonv0.65b0
Install
2.8s avg
Import
Disk
22MB
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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 23.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.8s · import 0.000s · 24MB
22MB installed
● package 22MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CeleryInstrumentor
from opentelemetry.instrumentation.celery import CeleryInstrumentor

This example demonstrates how to set up OpenTelemetry tracing for a Celery application. It configures a `TracerProvider` with a `BatchSpanProcessor` and an `OTLPSpanExporter` (or `ConsoleSpanExporter` as a fallback). Crucially, the `CeleryInstrumentor` is initialized within the `worker_process_init` signal handler to ensure proper tracing context propagation across Celery's prefork worker model. Remember to set `OTEL_SERVICE_NAME` and `OTEL_EXPORTER_OTLP_ENDPOINT` environment variables for OTLP export.

import os from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter from opentelemetry.instrumentation.celery import CeleryInstrumentor from celery import Celery from celery.signals import worker_process_init # Configure OpenTelemetry Tracer Provider # For local development, ConsoleSpanExporter is useful. For production, OTLPSpanExporter. resource = Resource.create({"service.name": os.environ.get('OTEL_SERVICE_NAME', 'celery-app')}) provider = TracerProvider(resource=resource) # Choose an exporter. For OTLP, ensure an OTLP endpoint is available (e.g., OpenTelemetry Collector). # Exporter endpoint can be configured via environment variable OTEL_EXPORTER_OTLP_ENDPOINT if os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT'): exporter = OTLPSpanExporter() else: exporter = ConsoleSpanExporter() processor = BatchSpanProcessor(exporter) provider.add_span_processor(processor) trace.set_tracer_provider(provider) # Initialize Celery app app = Celery( 'my_celery_app', broker=os.environ.get('CELERY_BROKER_URL', 'redis://localhost:6379/0'), backend=os.environ.get('CELERY_RESULT_BACKEND', 'redis://localhost:6379/0') ) # Crucial: Initialize instrumentation AFTER Celery worker process is initialized @worker_process_init.connect(weak=False) def init_celery_tracing(*args, **kwargs): CeleryInstrumentor().instrument() print("OpenTelemetry Celery instrumentation initialized.") # Define a simple task @app.task def add(x, y): with trace.get_current_tracer().start_as_current_span("add.task.execution") as span: result = x + y span.set_attribute("sum", result) print(f"Task 'add' executed: {x} + {y} = {result}") return result if __name__ == '__main__': # Example of how to send a task (typically done from a separate producer process) print("Sending task...") task = add.delay(1, 2) print(f"Task ID: {task.id}") print(f"Task result: {task.get(timeout=10)}") # To run the worker (from your terminal): # OTEL_SERVICE_NAME="celery-worker" OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317" celery -A your_module_name worker -l info
Debug
Known issues
gotchaOpenTelemetry Python contrib packages, including Celery instrumentation, are currently in beta. This means APIs and behavior may change in future versions, and they are generally not recommended for production environments without careful consideration.
fix
Monitor official OpenTelemetry Python releases for stable versions and semantic convention updates. Review changelogs carefully before upgrading.
affects: All versions up to 0.61b0
breakingThe `CeleryInstrumentor` must be initialized within the `celery.signals.worker_process_init` signal handler when using Celery's prefork worker model. Failing to do so can lead to incorrect or missing traces, as child processes may not inherit the parent's OpenTelemetry state properly.
fix
Always connect `CeleryInstrumentor().instrument()` to the `worker_process_init` signal, as shown in the quickstart example.
affects: All versions
gotchaTelemetry data (traces, metrics) will not be collected or visible without a properly configured OpenTelemetry SDK and an exporter (e.g., OTLP, Jaeger, Console). Ensure `TracerProvider`, `SpanProcessor`, and an `Exporter` are set up.
fix
Explicitly configure and set a global `TracerProvider` and add a `SpanProcessor` with a chosen `Exporter` during application startup, preferably before Celery tasks are defined or run, and within `worker_process_init` for workers.
affects: All versions
gotchaOpenTelemetry Python is adopting a semantic convention migration plan. While currently focused on HTTP-related instrumentations, this may eventually affect all types of instrumentations, including Celery, and could introduce breaking changes to attribute names or span structures.
fix
Stay informed about OpenTelemetry semantic convention updates and consult the `opentelemetry-python-contrib` documentation for specific instrumentation status and migration guides.
affects: Future stable versions (post-beta)
gotchaThe `opentelemetry-instrumentation-celery` package only instruments Celery itself. Depending on your Celery broker (e.g., Redis, RabbitMQ) and result backend, you might need to install additional OpenTelemetry instrumentations (e.g., `opentelemetry-instrumentation-redis`, `opentelemetry-instrumentation-amqp`).
fix
Identify all external libraries used by your Celery application (broker, backend, databases, HTTP clients) and install their corresponding OpenTelemetry instrumentations where available.
affects: All versions
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
celeryrequiredThe library instruments Celery; Celery must be installed separately.
opentelemetry-sdkrequiredProvides the core OpenTelemetry SDK components required for tracing and exporting telemetry data.
Agent activity
32 hits · last 30 days
node
28
OpenAI (training)
1
Resources
opentelemetry-instrumentation-celery — pip install opentelemetry-instrumentation-celery · libregistry