Registry /
observability / opentelemetry-instrumentation-celery
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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 23.9MB
glibcpy 3.10–3.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.fixMonitor 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.fixAlways 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.fixExplicitly 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.fixStay 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`).fixIdentify 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.