index.mdx

title	description
Celery	Learn about using Sentry with Celery.

The Celery integration adds support for the Celery Task Queue System.

Install

Install sentry-sdk from PyPI with the celery extra:

pip install --upgrade 'sentry-sdk[celery]'

Configure

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

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.

In addition to capturing errors, you can use Sentry for distributed tracing and profiling. Select what you'd like to install to get the corresponding installation and configuration instructions below.

Set up Sentry in Celery Daemon or Worker Processes

<OnboardingOptionButtons options={["error-monitoring", "performance", "profiling"]} />

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="___PUBLIC_DSN___",
        # Add request headers and IP for users,
        # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
        send_default_pii=True,
        # ___PRODUCT_OPTION_START___ performance
        # Set traces_sample_rate to 1.0 to capture 100%
        # of transactions for tracing.
        traces_sample_rate=1.0,
        # ___PRODUCT_OPTION_END___ performance
        # ___PRODUCT_OPTION_START___ profiling
        # Set profiles_sample_rate to 1.0 to profile 100%
        # of sampled transactions.
        # We recommend adjusting this value in production.
        profiles_sample_rate=1.0,
        # ___PRODUCT_OPTION_END___ profiling
    )

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

The 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 signal instead.

Set up Sentry in Your Application

<OnboardingOptionButtons options={["error-monitoring", "performance", "profiling"]} />

from tasks import add
import sentry_sdk

def main():
    # Initializing Sentry SDK in our process
    sentry_sdk.init(
        dsn="___PUBLIC_DSN___",
        # Add data like request headers and IP for users, if applicable;
        # see https://docs.sentry.io/platforms/python/data-management/data-collected/ for more info
        send_default_pii=True,
        # ___PRODUCT_OPTION_START___ performance
        # Set traces_sample_rate to 1.0 to capture 100%
        # of transactions for tracing.
        traces_sample_rate=1.0,
        # ___PRODUCT_OPTION_END___ performance
        # ___PRODUCT_OPTION_START___ profiling
        # Set profiles_sample_rate to 1.0 to profile 100%
        # of sampled transactions.
        # We recommend adjusting this value in production.
        profiles_sample_rate=1.0,
        # ___PRODUCT_OPTION_END___ profiling
    )

    # Enqueueing a task to be processed by Celery
    with sentry_sdk.start_transaction(name="calling-a-celery-task"):
        result = add.delay(4, 4)

if __name__ == "__main__":
    main()

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), and have your Celery configured to use the same settings as config_from_object, there's no need to initialize the Celery SDK separately.

Verify

To confirm that your SDK is initialized on worker start, pass debug=True to sentry_sdk.init(). This will add extra output to your Celery logs when the SDK is initialized. If you see the output during worker startup, and not just after a task has started, then it's working correctly.

The snippet below includes an intentional ZeroDivisionError in the Celery task that will be captured by Sentry. To trigger the error call debug_sentry.delay():

from celery import Celery, signals
import sentry_sdk

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

@signals.celeryd_init.connect
def init_sentry(**_kwargs):
    sentry_sdk.init(...)  # same as above

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

Sentry uses custom message headers for distributed tracing. For Celery versions 4.x, with message protocol of version 1, this functionality is broken, and Celery fails to propagate custom headers to the worker. Protocol version 2, which is the default since Celery version 4.0, is not affected.

The fix for the custom headers propagation issue was introduced to Celery project (PR) starting with version 5.0.1. However, the fix was not backported to versions 4.x.

Options

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

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

  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.

  The default is True.

  See Distributed Traces below to learn how to get more fine grained control over distributed tracing in Celery tasks.

• monitor_beat_tasks:

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

  See Celery Beat Auto Discovery to learn more.

  The default is False.

• exclude_beat_tasks:

  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 to learn more.

  The default is None.

Distributed Traces

Distributed tracing extends the trace from the code that's running your Celery task so that it includes the code that initiated the task.

You can disable this globally with the propagate_traces parameter, documented above. 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:

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

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.

Supported Versions

• Celery: 4.0+
• Python: 3.6+