---
title: "Celery"
description: "Learn how to set up Sentry in your Celery app, capture your first events and traces, and view them in Sentry."
url: https://docs.sentry.io/platforms/python/integrations/celery/
---

# Celery for Python

If you're using stream mode, this page's references to "transaction" should be applied to service spans instead. See [Streamed Spans](https://docs.sentry.io/platforms/python/tracing/streamed-spans.md) for more information.

## [Prerequisites](https://docs.sentry.io/platforms/python/integrations/celery.md#prerequisites)

You need:

* A Sentry [account](https://sentry.io/signup/) and [project](https://docs.sentry.io/product/projects.md)

* Your application up and running

* Celery:

  * `4.4.7+` (SDK <3.0)
  * `5.0.0+` (SDK 3.0+)

* Python:

  * `3.6+` (SDK <3.0)
  * `3.7+` (SDK 3.0+)

## [Install](https://docs.sentry.io/platforms/python/integrations/celery.md#install)

Run the command for your preferred package manager to add the Sentry SDK to your application:

```bash
pip install "sentry-sdk"
```

*Other available variations of the above snippet: uv, poetry*

This guide requires `sentry-sdk` version 2.70.0 or later. If you already have the SDK installed, upgrade it with `pip install --upgrade sentry-sdk`.

## [Configure](https://docs.sentry.io/platforms/python/integrations/celery.md#configure)

**Error Monitoring** starts working as soon as you call `sentry_sdk.init()`. **Logs** and **Application Metrics** need no extra configuration when using `sentry_sdk.logger` and `sentry_sdk.metrics`, and you'll learn how to send them in steps [#3](https://docs.sentry.io/platforms/python/integrations/celery.md#send-logs) and [#4](https://docs.sentry.io/platforms/python/integrations/celery.md#send-application-metrics-). This guide also enables **Tracing** and **Profiling**.

Want to learn more about these features?

* [**Issues**](https://docs.sentry.io/product/issues.md) (always enabled): Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and crashes. If you have something that looks like an exception, Sentry can capture it.
* [**Tracing**](https://docs.sentry.io/product/tracing.md): Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
* [**Profiling**](https://docs.sentry.io/product/profiling.md): Gain deeper insight than traditional tracing without custom instrumentation, letting you discover slow-to-execute or resource-intensive functions in your app.
* [**Logs**](https://docs.sentry.io/product/logs.md): Centralize and analyze your application logs to correlate them with errors and performance issues. Search, filter, and visualize log data to understand what's happening in your applications.
* [**Application Metrics**](https://docs.sentry.io/product/metrics.md) (always enabled): Track and analyze custom application metrics, such as response times and database query durations, to understand trends and patterns in your application's performance and behavior over time.

### [Initialize the Sentry SDK](https://docs.sentry.io/platforms/python/integrations/celery.md#initialize-the-sentry-sdk)

Configuration should happen as **early as possible** in your application's lifecycle.

The init snippets also turn on:

* Collection of task arguments in error events: via [`data_collection`](https://docs.sentry.io/platforms/python/configuration/options.md#data_collection)
* Tracing: via [`traces_sample_rate`](https://docs.sentry.io/platforms/python/configuration/options.md#traces_sample_rate)
* Profiling: via [`profile_session_sample_rate`](https://docs.sentry.io/platforms/python/configuration/options.md#profile_session_sample_rate) and [`profile_lifecycle`](https://docs.sentry.io/platforms/python/configuration/options.md#profile_lifecycle)

Don't need a feature? Remove its options from the snippets.

If you have the `celery` package in your dependencies, the Celery integration will be enabled automatically when you initialize the Sentry SDK.

Make sure that the call to `sentry_sdk.init()` is loaded on worker startup and not only in the module where your tasks are defined. Otherwise, the initialization may happen too late and events might not get reported.

### [Set up Celery Without Django](https://docs.sentry.io/platforms/python/integrations/celery.md#set-up-celery-without-django)

When using Celery without Django, you'll need to initialize the Sentry SDK in both your application and the Celery worker processes spawned by the Celery daemon.

#### [Set up Sentry in Celery Daemon or Worker Processes](https://docs.sentry.io/platforms/python/integrations/celery.md#set-up-sentry-in-celery-daemon-or-worker-processes)

```python
from celery import Celery, signals
import sentry_sdk

# Initializing Celery
app = Celery("tasks", broker="...")

# Initialize Sentry SDK on Celery startup
@signals.celeryd_init.connect
def init_sentry(**_kwargs):
    sentry_sdk.init(
        dsn="https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
        # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected
        data_collection={
            "queues": True,
        },
        # Enables Tracing.
        # Set to 1.0 to capture 100% of spans for tracing.
        # We recommend reducing this value in production.
        traces_sample_rate=1.0,
        # Enables Profiling.
        # Set to 1.0 to profile 100% of sessions.
        profile_session_sample_rate=1.0,
        # Profiles are collected while a transaction is active.
        profile_lifecycle="trace",
    )

# Task definitions go here
@app.task
def add(x, y):
    return x + y
```

The [`celeryd_init`](https://docs.celeryq.dev/en/stable/userguide/signals.html?#celeryd-init) signal is triggered when the Celery daemon starts, before the worker processes are spawned. If you need to initialize Sentry for each individual worker process, use the [`worker_init`](https://docs.celeryq.dev/en/stable/userguide/signals.html?#worker-init) signal instead.

#### [Set up Sentry in Your Application](https://docs.sentry.io/platforms/python/integrations/celery.md#set-up-sentry-in-your-application)

```python
from tasks import add
import sentry_sdk

def main():
    # Initializing Sentry SDK in our process
    sentry_sdk.init(
        dsn="https://<key>@o<orgId>.ingest.sentry.io/<projectId>",
        # Check https://docs.sentry.io/platforms/python/data-management/data-collected/ to configure what data is collected
        data_collection={
            "queues": True,
        },
        # Enables Tracing.
        # Set to 1.0 to capture 100% of spans for tracing.
        # We recommend reducing this value in production.
        traces_sample_rate=1.0,
        # Enables Profiling.
        # Set to 1.0 to profile 100% of sessions.
        profile_session_sample_rate=1.0,
        # Profiles are collected while a transaction is active.
        profile_lifecycle="trace",
    )

    # Enqueueing a task to be processed by Celery
    with sentry_sdk.start_transaction(name="calling-a-celery-task"):
    # or sentry_sdk.traces.start_span(name="calling-a-celery-task", parent_span=None) in stream mode
        result = add.delay(4, 4)

if __name__ == "__main__":
    main()
```

### [Set up Celery With Django](https://docs.sentry.io/platforms/python/integrations/celery.md#set-up-celery-with-django)

If you're using Celery with Django in a typical setup, have initialized the SDK in your `settings.py` file (as described in the [Django integration documentation](https://docs.sentry.io/platforms/python/integrations/django.md#configure)), and have your Celery configured to use the same settings as [`config_from_object`](https://docs.celeryq.dev/en/stable/django/first-steps-with-django.html), there's no need to initialize the Celery SDK separately.

To further customize your setup, review the [Options section](https://docs.sentry.io/platforms/python/integrations/celery.md#options) below.

### [Capturing Errors](https://docs.sentry.io/platforms/python/integrations/celery.md#capturing-errors)

Sentry automatically captures errors and exceptions raised in your Celery tasks and reports them as issues.

To learn how to manually report issues, see [Capturing Errors](https://docs.sentry.io/platforms/python/usage.md).

### [Instrumenting Your App](https://docs.sentry.io/platforms/python/integrations/celery.md#instrumenting-your-app)

The Sentry SDK automatically creates spans for your Celery tasks, and propagates the trace from the code that enqueues a task to the worker that runs it.

You can also manually capture performance data – see [Custom Instrumentation](https://docs.sentry.io/platforms/python/tracing/instrumentation/custom-instrumentation.md) to learn more.

#### [Distributed Traces](https://docs.sentry.io/platforms/python/integrations/celery.md#distributed-traces)

Distributed tracing extends the trace from the code running your Celery task to include the code that initiated the task.

You can disable this globally with the `propagate_traces` option, documented in the [options](https://docs.sentry.io/platforms/python/integrations/celery.md#options) below. If you set `propagate_traces` to `False`, all Celery tasks will start their own trace.

If you want to have more fine-grained control over trace distribution, you can override the `propagate_traces` option by passing the `sentry-propagate-traces` header when starting the Celery task:

The `CeleryIntegration` does not utilize the `traces_sample_rate` config option for deciding if a trace should be propagated into a Celery task.

```python
import sentry_sdk

# Enable global distributed traces (this is the default, just to be explicit)
sentry_sdk.init(
    # same as above
    integrations=[
        CeleryIntegration(
            propagate_traces=True
        ),
    ],
)

# This will propagate the trace:
my_task_a.delay("some parameter")

# This will propagate the trace:
my_task_b.apply_async(
    args=("some_parameter", )
)

# This will NOT propagate the trace. The task will start its own trace:
my_task_b.apply_async(
    args=("some_parameter", ),
    headers={"sentry-propagate-traces": False},
)

# Note: overriding the tracing behaviour using `task_x.delay()` is not possible.
```

## [Send Logs](https://docs.sentry.io/platforms/python/integrations/celery.md#send-logs)

Use `sentry_sdk.logger` to send structured logs at different levels. You can include searchable attributes with each message.

To capture records from Python's standard-library `logging` module or Loguru, configure `capture_sentry_logs=True` on the corresponding integration. See the [standard logging](https://docs.sentry.io/platforms/python/integrations/logging.md) and [Loguru](https://docs.sentry.io/platforms/python/integrations/loguru.md) integration guides.

See [Set Up Logs](https://docs.sentry.io/platforms/python/logs.md) for all available logging methods and formatting options.

```python
import sentry_sdk

sentry_sdk.logger.info("Order processed {order_id}", order_id="order-123")
sentry_sdk.logger.warning("Rate limit reached", attributes={"endpoint": "/api/orders"})
```

## [Send Application Metrics NEW](https://docs.sentry.io/platforms/python/integrations/celery.md#send-application-metrics-)

Use `sentry_sdk.metrics` to send counters, gauges, and distributions from your app. Metrics are enabled by default after you initialize the SDK.

See [Set Up Metrics](https://docs.sentry.io/platforms/python/metrics.md) for all available metric types and configuration options.

```python
import sentry_sdk

sentry_sdk.metrics.count("checkout.failed", 1)
sentry_sdk.metrics.gauge("active_connections", 42)
sentry_sdk.metrics.distribution("api_latency", 187, unit="millisecond")
```

## [Verify Your Setup](https://docs.sentry.io/platforms/python/integrations/celery.md#verify-your-setup)

Let's test your setup and confirm that data reaches your Sentry project.

Add a task that raises an exception, then call `debug_sentry.delay()` from a running Celery worker:

```python
@app.task
def debug_sentry():
    1 / 0
```

### [View Captured Data in Sentry](https://docs.sentry.io/platforms/python/integrations/celery.md#view-captured-data-in-sentry)

Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear).

Need help locating captured data in your Sentry project?

* Open the [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) page and select an error from the issues list to view the full details and context of this error. For more details, see the [Issue Details documentation](https://docs.sentry.io/product/issues/issue-details.md).
* Open the [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/) page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click [here](https://docs.sentry.io/product/sentry-basics/getting-started-tutorial/generate-first-error.md#ui-walkthrough).
* Open the [**Profiles**](https://sentry.io/orgredirect/organizations/:orgslug/profiling/) page to see your slowest functions and an aggregate flame graph of your most frequent code paths. If tracing is enabled, select a transaction to see the flame graph for that part of your app. For more information, click [here](https://docs.sentry.io/product/profiling/profile-details.md).
* Open the [**Logs**](https://sentry.io/orgredirect/organizations/:orgslug/explore/logs/) page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click [here](https://docs.sentry.io/product/logs.md#overview).
* Open the [**Application Metrics**](https://sentry.io/orgredirect/organizations/:orgslug/explore/metrics) page to view and analyze your metrics. For more details, see this [interactive walkthrough](https://docs.sentry.io/product/metrics.md#overview).

## [Options](https://docs.sentry.io/platforms/python/integrations/celery.md#options)

In stream mode, these options still work as described, but apply to service spans instead of transactions.

To set options on `CeleryIntegration` to change its behavior, add it explicitly to your `sentry_sdk.init()`:

```python
import sentry_sdk
from sentry_sdk.integrations.celery import CeleryIntegration

sentry_sdk.init(
    # same as above
    integrations=[
        CeleryIntegration(
            monitor_beat_tasks=True,
            exclude_beat_tasks=[
                "unimportant-task",
                "payment-check-.*"
            ],
        ),
    ],
)
```

You can pass the following keyword arguments to `CeleryIntegration()`:

### [propagate\_traces](https://docs.sentry.io/platforms/python/integrations/celery.md#propagate_traces)

| Type    | `bool` |
| ------- | ------ |
| Default | `True` |

Propagate Sentry tracing information to the Celery task. This makes it possible to link Celery task errors to the function that triggered the task.

If this is set to `False`:

* errors in Celery tasks won't be matched to the triggering function.
* your Celery tasks will start a new trace and won't be connected to the trace in the calling function.

See [Distributed Traces](https://docs.sentry.io/platforms/python/integrations/celery.md#distributed-traces) to learn how to get more fine-grained control over distributed tracing in Celery tasks.

### [monitor\_beat\_tasks](https://docs.sentry.io/platforms/python/integrations/celery.md#monitor_beat_tasks)

| Type    | `bool`  |
| ------- | ------- |
| Default | `False` |

Turn auto-instrumentation on or off for Celery Beat tasks using Sentry Crons.

See [Celery Beat Auto Discovery](https://docs.sentry.io/platforms/python/integrations/celery/crons.md) to learn more.

### [exclude\_beat\_tasks](https://docs.sentry.io/platforms/python/integrations/celery.md#exclude_beat_tasks)

| Type    | `list[str]` |
| ------- | ----------- |
| Default | `None`      |

A list of Celery Beat tasks that should be excluded from auto-instrumentation using Sentry Crons. Only applied if `monitor_beat_tasks` is set to `True`.

The list can contain strings with the names of tasks in the Celery Beat schedule to be excluded. It can also include regular expressions to match multiple tasks. For example, if you include `"payment-check-.*"` every task starting with `payment-check-` will be excluded from auto-instrumentation.

See [Celery Beat Auto Discovery](https://docs.sentry.io/platforms/python/integrations/celery/crons.md) to learn more.

## [Next Steps](https://docs.sentry.io/platforms/python/integrations/celery.md#next-steps)

At this point, you should have integrated Sentry into your Celery application. Here's what to explore next:

* Explore [practical guides](https://docs.sentry.io/get-started/guides.md) on what to monitor, log, track, and investigate after setup
* [Set up Agent Tracing](https://docs.sentry.io/platforms/python/agent-tracing.md) to monitor your AI systems
* Learn how to [manually capture errors](https://docs.sentry.io/platforms/python/usage.md)

Are you having problems setting up the SDK?

* Find various topics in [Troubleshooting](https://docs.sentry.io/platforms/python/troubleshooting.md)
* [Get support](https://www.sentry.help/en/)

## Pages in this section

- [Crons](https://docs.sentry.io/platforms/python/integrations/celery/crons.md)