feat(python): Document default span attrs in Celery, update for 3.0 (#14365)

Document what span attributes will be attached to transactions by
default by our builtin integrations. This PR updates Celery. Rest will
follow.

I created a new 3.x page for this since it's new behavior in 3.0.

---------

Co-authored-by: Alex Krawiec <[email protected]>

Author: sentrivana

docs/platforms/python/integrations/celery/index__v3.x.mdx

@@ -0,0 +1,266 @@
+---
+title: Celery
+description: "Learn about using Sentry with Celery."
+---
+
+The Celery integration adds support for the [Celery Task Queue System](https://docs.celeryq.dev/).
+
+## Install
+
+Install `sentry-sdk` from PyPI with the `celery` extra:
+
+```bash {tabTitle:pip}
+pip install "sentry-sdk[celery]"
+```
+```bash {tabTitle:uv}
+uv add "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.
+
+<Alert>
+Make sure you call `sentry_sdk.init()` when the worker process starts, 
+  not just in the module that defines your tasks. Otherwise, the
+  initialization may happen too late, causing events to go unreported.
+</Alert>
+
+### 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](/concepts/key-terms/tracing/) and [profiling](/product/explore/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"]}
+/>
+
+```python {filename:tasks.py}
+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
+        # To collect profiles for all profile sessions,
+        # set `profile_session_sample_rate` to 1.0.
+        profile_session_sample_rate=1.0,
+        # Profiles will be automatically collected while
+        # there is an active span.
+        profile_lifecycle="trace",
+        # ___PRODUCT_OPTION_END___ profiling
+    )
+
+# 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
+
+<OnboardingOptionButtons
+  options={["error-monitoring", "performance", "profiling"]}
+/>
+
+```python {filename:main.py}
+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
+        # To collect profiles for all profile sessions,
+        # set `profile_session_sample_rate` to 1.0.
+        profile_session_sample_rate=1.0,
+        # Profiles will be automatically collected while
+        # there is an active span.
+        profile_lifecycle="trace",
+        # ___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](/platforms/python/integrations/django/#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.
+
+## 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()`:
+
+```python {filename:tasks.py}
+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
+```
+
+<Alert title="Note on distributed tracing">
+
+Sentry uses custom message headers for distributed tracing. For Celery versions 4.x, with [message protocol of version 1](https://docs.celeryq.dev/en/stable/internals/protocol.html#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](https://github.com/celery/celery/pull/6374)) starting with version 5.0.1. However, the fix was not backported to versions 4.x.
+
+</Alert>
+
+## Options
+
+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`
+
+  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](#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 <PlatformLink to="/crons/#celery-beat-auto-discovery">Celery Beat Auto Discovery</PlatformLink> 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 <PlatformLink to="/crons/#celery-beat-auto-discovery">Celery Beat Auto Discovery</PlatformLink> to learn more.
+
+  The default is `None`.
+
+## Behavior
+
+### Distributed Traces
+
+Distributed tracing connects the trace of your Celery task to the trace of the code that started the task, giving you a complete view of the entire workflow.
+
+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.
+
+```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.
+```
+
+### Default Span Attributes
+
+A set of predefined span attributes will be attached to Celery transactions by default. These can also be used for sampling since they will also be accessible via the `sampling_context` dictionary in the [`traces_sampler`](/platforms/python/configuration/options/#traces_sampler).
+
+  | Span Attribute              | Description                                           |
+  | --------------------------- | ----------------------------------------------------- |
+  | `celery.job.args.{index}`   | Positional arguments provided to the task, serialized |
+  | `celery.job.kwargs.{kwarg}` | Keyword arguments provided to the task, serialized    |
+  | `celery.job.task`           | Task name                                             |
+
+These attributes will also be sent to Sentry. If you don't want that, you can filter them out using a custom [`before_send`](/platforms/python/configuration/options/#before_send) function.
+
+## Supported Versions
+
+- Celery: 4.4.7+
+- Python: 3.7+
+
+<Include name="python-use-older-sdk-for-legacy-support.mdx" />