django-lambda-tasks 0.11.0__tar.gz → 0.11.1__tar.gz

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.1}/.github/workflows/ci.yml

@@ -53,3 +53,35 @@ jobs:
       - name: Run tests
         run: |
           uv run pytest --cov-branch --cov-report term-missing --cov=tests/ --cov=lambda_tasks/
+
+  sentry-prerelease:
+    # Exercise the Sentry integration against the latest 3.x pre-release of
+    # sentry-sdk (stream mode). The committed dev dependency is pinned to the
+    # stable 2.x line; this job overrides it at runtime via `uv run --with`
+    # without touching pyproject.toml, so regressions in the 3.x API are caught
+    # before the SDK goes stable.
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: lambda_tasks_test
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: '3.14'
+      - name: Run tests against the latest sentry-sdk 3.x pre-release
+        run: |
+          uv run --prerelease=allow --with "sentry-sdk>=3.0.0b1" \
+            pytest --cov-branch --cov-report term-missing --cov=tests/ --cov=lambda_tasks/

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.1}/.kiro/steering/product.md

@@ -315,21 +315,29 @@ def my_task(*, user_id: int) -> None:
 
 ## Sentry
 
-The library does not call `sentry_sdk.init(...)` — the host application owns Sentry setup (typically `DjangoIntegration` + `AwsLambdaIntegration`). The problem those integrations leave is attribution: on Lambda, `AwsLambdaIntegration` names every event's transaction after the Lambda function, so all tasks share one transaction (and a single invocation-level transaction is shared across a batch of SQS records); on AWS Batch there is no request and no Lambda integration, so the transaction and URL are `"--"` and `traces_sample_rate` produces no trace for the task body. Either way you cannot tell which task ran or raised.
+The library does not call `sentry_sdk.init(...)` — the host application owns Sentry setup (typically `DjangoIntegration` + `AwsLambdaIntegration`). The problem those integrations leave is attribution: on Lambda, `AwsLambdaIntegration` names every event's transaction after the Lambda function, so all tasks look alike; on AWS Batch there is no request and no Lambda integration, so the transaction/URL are `"--"`. Either way you cannot tell which task ran or raised.
 
-`lambda_tasks.sentry.task_scope(*, task_name, message_id, n_retries)` fixes this. `execute_immediately` wraps the task body in it, which — when a Sentry client is active — opens an isolated `sentry_sdk.new_scope()` **and a per-task root span/transaction** named after the task. This gives one trace per task on both Lambda and Batch. It records, both on the span and as scope tags:
+`lambda_tasks.sentry.task_scope(*, task_name, message_id, n_retries)` fixes this. `execute_immediately` wraps the task body in it, which — when a Sentry client is active — opens an isolated `sentry_sdk.new_scope()` and traces the task. Trace shape depends on whether a trace is already active:
 
-- transaction/span **name** = the fully-qualified task name (e.g. `myapp.tasks.my_task`)
-- `lambda_task` = task name
+- **Lambda** — `AwsLambdaIntegration` already started an invocation transaction, so the task is traced as a **child span** of it (not a second transaction). This is deliberate: a nested *transaction* per task inherited (rather than independently re-rolled) the invocation's sampling decision, doubling transaction volume and defeating `traces_sample_rate`. A child span is sent only if its parent is sampled, so sampling is respected. `_start_task_root` picks child-vs-root by checking `sentry_sdk.get_current_scope().transaction` (2.x only; on 3.0 `start_span` is automatically root-or-child).
+- **Batch** (nothing active) — the task starts its **own root transaction** so it is still traced.
+
+It records, both on the span and as scope tags:
+
+- `lambda_task` = fully-qualified task name (e.g. `myapp.tasks.my_task`) — also the task span's name
 - `lambda_task.message_id` = the `TaskRecord` primary key
 - `lambda_task.n_retries` = the retry counter
-- `lambda_task.runtime` = the physical execution environment, read from the AWS environment: `AWS_LAMBDA_FUNCTION_NAME` on Lambda or `AWS_BATCH_JQ_NAME` (the Batch job queue name) on Batch; omitted when neither is present
+- `lambda_task.runtime` = the execution environment, from the AWS environment: `AWS_LAMBDA_FUNCTION_NAME` on Lambda or `AWS_BATCH_JQ_NAME` (Batch job queue name); omitted when neither is present
+
+`task_scope` deliberately does **not** call `scope.set_transaction_name(task_name)`: on Lambda that would rename the shared invocation transaction (fighting across sibling records in a batch) and, on SDK 3.0 stream mode, corrupt the root-segment naming. Error attribution relies on the `lambda_task` **tag** instead, which is reliable on both SDKs and independent of sampling.
+
+**Reporting task failures:** the executor catches task exceptions (recording `FAILED` and not re-raising), so `lambda_tasks.sentry.capture_task_exception()` is called on the two **terminal** failure branches in `models.py` (plain failure and max-retries-exceeded) to report the error via `sentry_sdk.capture_exception()`. This is essential on 3.0, where a merely-caught exception produces no error event. The **retry** branch deliberately does not capture — transient, to-be-re-enqueued failures would flood Sentry; only terminal failures are reported.
 
-The scope covers the success, retry, and failure paths, so task-logic exceptions (which the executor records as `FAILED` and does not re-raise to the handler) still carry the task name when captured by Sentry. The scope tags are kept in addition to span metadata so error events are attributed even when the performance span is not sampled.
+**Error-level log forwarding:** on sentry-sdk 2.x, `LoggingIntegration` defaulted to `event_level=ERROR`, so `task_logger.error(...)` became Sentry events automatically. On 3.0 the default is `None`, so hosts that want error logs reported must configure `LoggingIntegration(event_level=logging.ERROR)` explicitly (the example app does this). This is a host-init concern, not something the library sets.
 
-**SDK version compatibility:** `task_scope` is future-proof across the sentry-sdk 2.x→3.0 boundary. On 2.x it uses `start_transaction` + `set_tag` (a root span must be a transaction to be sent); on 3.0 (stream mode, where transactions are removed and tags no longer propagate to spans) it uses `start_span` + `set_attribute`. The correct API is detected at runtime via `hasattr`, so no code change is needed when the host upgrades the SDK.
+**SDK version compatibility:** `task_scope` is future-proof across the sentry-sdk 2.x→3.0 boundary and verified against both 2.74 and 3.0.0b4. On 2.x it uses `start_transaction` + `set_tag` for a root and `start_span` for a child; on 3.0 (stream mode) `start_span` is both root and child and metadata is attached via `set_attribute`. The correct API is detected at runtime via `hasattr`, so no code change is needed when the host upgrades the SDK.
 
-`task_scope` is a no-op when `sentry_sdk` is not installed or no client is initialised, so Sentry is not a dependency of the library. `sentry-sdk` is a dev dependency only, for the test suite. No custom Sentry integration is needed — per-task tracing at the one execution entry point covers both Lambda and Batch.
+`task_scope` and `capture_task_exception` are no-ops when `sentry_sdk` is not installed or no client is initialised, so Sentry is not a dependency of the library. `sentry-sdk` is a dev dependency only (pinned `>=2,<3`), for the test suite. No custom Sentry integration is needed — per-task tracing at the one execution entry point covers both Lambda and Batch.
 
 ## Built-in Tasks
 

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.1}/.kiro/steering/structure.md

@@ -16,7 +16,7 @@ django-lambda-tasks/
 │   ├── decorators.py           # LambdaTaskWrapper, @lambda_task
 │   ├── handler.py              # AWS Lambda entry point + AWS Batch container entry point (main)
 │   ├── logging.py              # task_logger — invocation-scoped LoggerAdapter
-│   ├── sentry.py               # task_scope — per-task Sentry transaction name + tags
+│   ├── sentry.py               # task_scope + capture_task_exception — per-task trace, tags, failure reporting
 │   ├── models.py               # TaskRecord, SQSLambdaTaskMessage, SQSLambdaTask
 │   ├── settings.py             # LambdaTasksSettings, constants, queue type helpers
 │   ├── secret_loader.py        # Resolves LAMBDA_TASKS_SECRET_* env vars at cold start
@@ -48,7 +48,7 @@ django-lambda-tasks/
 - `environment_loader.py` — loads env vars from a Secrets Manager secret at cold start; validates flat JSON format; idempotent via `_loaded` sentinel
 - `secret_loader.py` — resolves `LAMBDA_TASKS_SECRET_*` env vars from Secrets Manager before Django starts; validates format, detects conflicts, batches API calls; idempotent via `_loaded` sentinel
 - `logging.py` — `task_logger` singleton; `message_id` set/cleared around each task execution
-- `sentry.py` — `task_scope` context manager; opens an isolated `new_scope` and a per-task root span/transaction named after the task, so both errors and performance traces are attributed per task (one trace per task on Lambda and Batch, not one invocation-level transaction shared across an SQS batch). Records `lambda_task` / `lambda_task.message_id` / `lambda_task.n_retries` / `lambda_task.runtime` as span metadata and scope tags; `lambda_task.runtime` is the execution environment read from `AWS_LAMBDA_FUNCTION_NAME` (Lambda) or `AWS_BATCH_JQ_NAME` (Batch). Future-proof across the SDK 2.x→3.0 boundary: it uses `start_transaction`+`set_tag` on 2.x and `start_span`+`set_attribute` on 3.0 (stream mode), detected at runtime via `hasattr`. A no-op when `sentry_sdk` is absent or uninitialised, so the library has no hard dependency on Sentry (`sentry-sdk` is a dev dependency only). Wrapped around the task body in `SQSLambdaTaskMessage.execute_immediately`
+- `sentry.py` — `task_scope` context manager + `capture_task_exception` helper. `task_scope` opens an isolated `new_scope` and traces the task: a **child span** of the invocation transaction on Lambda (where `AwsLambdaIntegration` already started one), or its **own root transaction** on Batch (nothing active). The child-span-on-Lambda behaviour avoids a second per-task transaction that would double trace volume and defeat `traces_sample_rate`. Records `lambda_task` / `lambda_task.message_id` / `lambda_task.n_retries` / `lambda_task.runtime` as span metadata and scope tags (runtime read from `AWS_LAMBDA_FUNCTION_NAME` or `AWS_BATCH_JQ_NAME`). Deliberately does not call `set_transaction_name` (would rename the shared invocation transaction and break 3.0 segment naming); error attribution rides on the `lambda_task` tag. `capture_task_exception` calls `sentry_sdk.capture_exception()` and is invoked on the terminal failure branches in `models.py` (plain failure + max-retries), since the executor catches exceptions without re-raising and 3.0 does not auto-report caught exceptions; the retry branch does not capture. Future-proof across the SDK 2.x→3.0 boundary (verified against 2.74 and 3.0.0b4): `start_transaction`/`set_tag`/child `start_span` on 2.x, `start_span`/`set_attribute` on 3.0, detected at runtime via `hasattr`. No-op when `sentry_sdk` is absent or uninitialised (`sentry-sdk` is a dev dependency only, pinned `>=2,<3`). Wrapped around the task body in `SQSLambdaTaskMessage.execute_immediately`. Note: `logger.error → Sentry event` needs `LoggingIntegration(event_level=logging.ERROR)` in the host init on 3.0 (default on 2.x); a host concern, demonstrated in the example app
 - `settings.py` — constants (`MAX_DELAY`, `MAX_TIMEOUT`, `MAX_BATCH_TIMEOUT`); `_is_sqs_queue()` and `_is_batch_queue()` helpers; `LambdaTasksSettings` instantiated fresh per use (reads live Django settings); `queue_max_timeout()` method returns 900 or 3600 based on queue type
 - `admin.py` — Django admin registration for `TaskRecord`
 - `apps.py` — Django `AppConfig`; `ready()` imports `checks` to register deployment checks and installs the local-executor shutdown signal handlers when `LOCAL_WORKERS > 0`

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.1}/.kiro/steering/tech.md

@@ -23,7 +23,7 @@ inclusion: always
 |---|---|---|
 | `pytest` | `>= 9.0.2` | Test runner |
 | `hypothesis` | present | Property-based testing (`.hypothesis/` directory exists) |
-| `sentry-sdk` | present | Testing the `task_scope` Sentry integration; not a runtime dependency |
+| `sentry-sdk` | `>=2,<3` | Testing the Sentry integration (`task_scope`, `capture_task_exception`); verified against 2.74 and 3.0.0b4. Not a runtime dependency |
 
 ## Package Manager
 

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-lambda-tasks
-Version: 0.11.0
+Version: 0.11.1
 Summary: Run async tasks in a lambda function
 Requires-Python: >=3.11
 Requires-Dist: awslambdaric
@@ -446,29 +446,54 @@ fields @timestamp, @message
 
 ### Sentry
 
-If your application uses Sentry, tasks are automatically attributed to their task name. Without this, Sentry's `AwsLambdaIntegration` names every event's transaction after the Lambda function (so all tasks share one transaction), and on AWS Batch there is no transaction at all (it shows as `"--"`) — so you cannot tell which task raised an error.
+If your application uses Sentry, task errors are automatically attributed to the task that raised them. Without this, Sentry's `AwsLambdaIntegration` names every event's transaction after the Lambda function (so all tasks look the same), and on AWS Batch there is no transaction at all (it shows as `"--"`) — so you cannot tell which task failed.
 
-You do **not** need to add a custom integration or change your `sentry_sdk.init(...)`. Keep your existing setup:
+Keep your existing `sentry_sdk.init(...)`. On **sentry-sdk 2.x** no change is needed. On **sentry-sdk 3.0+** one option changed default and must be set explicitly if you want error-level logs reported (see below):
 
 ```python
+import logging
+from sentry_sdk.integrations.logging import LoggingIntegration
+
 sentry_sdk.init(
     dsn=SENTRY_DSN,
-    integrations=[DjangoIntegration(), AwsLambdaIntegration()],
-    # ...
+    integrations=[
+        DjangoIntegration(),
+        AwsLambdaIntegration(),
+        # Only needed on sentry-sdk 3.0+: its default event_level is None, so
+        # logger.error(...) no longer becomes a Sentry event. On 2.x this was
+        # the default and setting it is harmless.
+        LoggingIntegration(event_level=logging.ERROR),
+    ],
+    traces_sample_rate=0.1,
 )
 ```
 
-When a task runs, `execute_immediately()` opens an isolated Sentry scope **and a per-task trace** (a root span/transaction named after the task). With `traces_sample_rate` set, you get one trace per task on both Lambda and Batch — rather than a single invocation-level transaction shared across a batch of SQS records. It sets, on both the span and the scope:
+#### What the library does per task
+
+When a task runs, `execute_immediately()` opens an isolated Sentry scope and traces the task:
+
+- **On Lambda**, the task is traced as a **child span** of the invocation transaction that `AwsLambdaIntegration` already started — not a second transaction. This keeps task tracing from doubling your transaction volume and respects `traces_sample_rate`.
+- **On Batch** (no Lambda integration, nothing active), the task starts **its own root transaction** so it is still traced.
+
+Either way it records, as both span metadata and scope tags:
+
+- `lambda_task` — the fully-qualified task name (e.g. `myapp.tasks.send_welcome_email`). This is also the task span's name.
+- `lambda_task.message_id`, `lambda_task.n_retries`
+- `lambda_task.runtime` — the execution environment, from the AWS environment: `AWS_LAMBDA_FUNCTION_NAME` on Lambda or `AWS_BATCH_JQ_NAME` (the Batch job queue name) on Batch. Omitted when neither is set (local/eager).
+
+Error attribution relies on the `lambda_task` **tag**, not on the transaction name, so it is reliable even when the trace is not sampled and regardless of whether the task ran as a child span (Lambda) or a root (Batch).
+
+#### Task failures are reported
+
+The executor catches a failing task's exception (recording a `FAILED` `TaskRecord`) rather than re-raising it. So the library calls `sentry_sdk.capture_exception()` itself on the **terminal failure paths** — a plain failure and max-retries-exceeded — to report the error to Sentry. This is essential on 3.0, where a merely-caught exception produces no error event at all.
 
-- the **transaction/span name** to the fully-qualified task name (e.g. `myapp.tasks.send_welcome_email`), overriding the Lambda function name on Lambda and replacing `"--"` on Batch
-- `lambda_task` (task name), `lambda_task.message_id`, and `lambda_task.n_retries`
-- `lambda_task.runtime` — the physical execution environment, derived from the AWS environment: the Lambda function name (`AWS_LAMBDA_FUNCTION_NAME`) on Lambda, or the Batch job queue name (`AWS_BATCH_JQ_NAME`) on Batch. Omitted when neither is set (e.g. local/eager execution).
+Transient, retryable failures (a task that will be re-enqueued) are **not** reported, to avoid flooding Sentry on every retry; only the final, terminal failure is captured.
 
-This covers task failures too: the executor records failures as `FAILED` `TaskRecord`s rather than re-raising, so the trace wraps the task body to ensure Sentry error events still carry the task name.
+#### SDK version compatibility
 
-The integration is future-proof across the sentry-sdk 2.x→3.0 boundary: it uses `start_transaction`/`set_tag` on 2.x and `start_span`/`set_attribute` on 3.0 (stream mode), chosen automatically at runtime — no change needed when you upgrade the SDK.
+The integration is future-proof across the sentry-sdk 2.x→3.0 boundary and verified against both 2.74 and 3.0.0b4. It uses `start_transaction`/`set_tag` on 2.x and `start_span`/`set_attribute` on 3.0 (stream mode), chosen automatically at runtime — no change needed when you upgrade.
 
-`sentry_sdk` is not a dependency of this library — if it is not installed or not initialised, the enrichment is a silent no-op.
+`sentry_sdk` is not a dependency of this library — if it is not installed or not initialised, all of the above is a silent no-op.
 
 ---
 

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.1}/README.md

@@ -434,29 +434,54 @@ fields @timestamp, @message
 
 ### Sentry
 
-If your application uses Sentry, tasks are automatically attributed to their task name. Without this, Sentry's `AwsLambdaIntegration` names every event's transaction after the Lambda function (so all tasks share one transaction), and on AWS Batch there is no transaction at all (it shows as `"--"`) — so you cannot tell which task raised an error.
+If your application uses Sentry, task errors are automatically attributed to the task that raised them. Without this, Sentry's `AwsLambdaIntegration` names every event's transaction after the Lambda function (so all tasks look the same), and on AWS Batch there is no transaction at all (it shows as `"--"`) — so you cannot tell which task failed.
 
-You do **not** need to add a custom integration or change your `sentry_sdk.init(...)`. Keep your existing setup:
+Keep your existing `sentry_sdk.init(...)`. On **sentry-sdk 2.x** no change is needed. On **sentry-sdk 3.0+** one option changed default and must be set explicitly if you want error-level logs reported (see below):
 
 ```python
+import logging
+from sentry_sdk.integrations.logging import LoggingIntegration
+
 sentry_sdk.init(
     dsn=SENTRY_DSN,
-    integrations=[DjangoIntegration(), AwsLambdaIntegration()],
-    # ...
+    integrations=[
+        DjangoIntegration(),
+        AwsLambdaIntegration(),
+        # Only needed on sentry-sdk 3.0+: its default event_level is None, so
+        # logger.error(...) no longer becomes a Sentry event. On 2.x this was
+        # the default and setting it is harmless.
+        LoggingIntegration(event_level=logging.ERROR),
+    ],
+    traces_sample_rate=0.1,
 )
 ```
 
-When a task runs, `execute_immediately()` opens an isolated Sentry scope **and a per-task trace** (a root span/transaction named after the task). With `traces_sample_rate` set, you get one trace per task on both Lambda and Batch — rather than a single invocation-level transaction shared across a batch of SQS records. It sets, on both the span and the scope:
+#### What the library does per task
+
+When a task runs, `execute_immediately()` opens an isolated Sentry scope and traces the task:
+
+- **On Lambda**, the task is traced as a **child span** of the invocation transaction that `AwsLambdaIntegration` already started — not a second transaction. This keeps task tracing from doubling your transaction volume and respects `traces_sample_rate`.
+- **On Batch** (no Lambda integration, nothing active), the task starts **its own root transaction** so it is still traced.
+
+Either way it records, as both span metadata and scope tags:
+
+- `lambda_task` — the fully-qualified task name (e.g. `myapp.tasks.send_welcome_email`). This is also the task span's name.
+- `lambda_task.message_id`, `lambda_task.n_retries`
+- `lambda_task.runtime` — the execution environment, from the AWS environment: `AWS_LAMBDA_FUNCTION_NAME` on Lambda or `AWS_BATCH_JQ_NAME` (the Batch job queue name) on Batch. Omitted when neither is set (local/eager).
+
+Error attribution relies on the `lambda_task` **tag**, not on the transaction name, so it is reliable even when the trace is not sampled and regardless of whether the task ran as a child span (Lambda) or a root (Batch).
+
+#### Task failures are reported
+
+The executor catches a failing task's exception (recording a `FAILED` `TaskRecord`) rather than re-raising it. So the library calls `sentry_sdk.capture_exception()` itself on the **terminal failure paths** — a plain failure and max-retries-exceeded — to report the error to Sentry. This is essential on 3.0, where a merely-caught exception produces no error event at all.
 
-- the **transaction/span name** to the fully-qualified task name (e.g. `myapp.tasks.send_welcome_email`), overriding the Lambda function name on Lambda and replacing `"--"` on Batch
-- `lambda_task` (task name), `lambda_task.message_id`, and `lambda_task.n_retries`
-- `lambda_task.runtime` — the physical execution environment, derived from the AWS environment: the Lambda function name (`AWS_LAMBDA_FUNCTION_NAME`) on Lambda, or the Batch job queue name (`AWS_BATCH_JQ_NAME`) on Batch. Omitted when neither is set (e.g. local/eager execution).
+Transient, retryable failures (a task that will be re-enqueued) are **not** reported, to avoid flooding Sentry on every retry; only the final, terminal failure is captured.
 
-This covers task failures too: the executor records failures as `FAILED` `TaskRecord`s rather than re-raising, so the trace wraps the task body to ensure Sentry error events still carry the task name.
+#### SDK version compatibility
 
-The integration is future-proof across the sentry-sdk 2.x→3.0 boundary: it uses `start_transaction`/`set_tag` on 2.x and `start_span`/`set_attribute` on 3.0 (stream mode), chosen automatically at runtime — no change needed when you upgrade the SDK.
+The integration is future-proof across the sentry-sdk 2.x→3.0 boundary and verified against both 2.74 and 3.0.0b4. It uses `start_transaction`/`set_tag` on 2.x and `start_span`/`set_attribute` on 3.0 (stream mode), chosen automatically at runtime — no change needed when you upgrade.
 
-`sentry_sdk` is not a dependency of this library — if it is not installed or not initialised, the enrichment is a silent no-op.
+`sentry_sdk` is not a dependency of this library — if it is not installed or not initialised, all of the above is a silent no-op.
 
 ---
 

django_lambda_tasks-0.11.1/lambda_tasks/sentry.py

@@ -0,0 +1,186 @@
+"""Sentry tracing/scope helpers for task execution.
+
+This library does not initialise Sentry itself — the host application owns
+``sentry_sdk.init(...)``. These helpers trace each task and attribute errors to
+the running task rather than to the Lambda function name (set by
+``AwsLambdaIntegration``) or to ``"--"`` (on AWS Batch, where no request or
+Lambda integration is active).
+
+Trace shape depends on whether a trace is already active:
+
+* **Lambda** — ``AwsLambdaIntegration`` starts a transaction per invocation, so
+  the task is traced as a **child span** of it. One transaction per invocation,
+  with the task span nested inside — not a second, competing transaction.
+* **Batch** (and anywhere nothing is active) — the task starts its **own root
+  transaction**, so it is still traced on its own.
+
+Why the child span matters: starting a nested *transaction* per task produced a
+second transaction that inherited (rather than independently re-rolled) the
+invocation's sampling decision, roughly doubling transaction volume and
+defeating ``traces_sample_rate``. A child span is sent only if its parent
+transaction is sampled, so sampling is respected.
+
+Error attribution does not depend on the trace being sampled: the ``lambda_task``
+scope tag carries the task name on every error event regardless.
+
+Future-proofing across the SDK 2.x → 3.0 boundary
+--------------------------------------------------
+The tracing API changed in SDK 3.0 (stream mode):
+
+* 2.x — a root is a *transaction* (``start_transaction``); a child uses
+  ``start_span``. Metadata is attached with ``set_tag``; ``Span.set_attribute``
+  does not exist, and ``Scope`` has a ``transaction`` attribute.
+* 3.0 — transaction mode is gone. ``start_span`` is both root (when nothing is
+  active) and child (when something is), metadata is attached via
+  ``set_attribute``, and ``Scope`` has no ``transaction`` attribute.
+
+We detect which API is present at runtime (via ``hasattr``) and use the correct
+one, so this module keeps working unchanged after an SDK upgrade. Metadata is
+attached with whichever setter the running span exposes (``set_attribute`` when
+available, otherwise ``set_tag``).
+
+Everything here degrades to a no-op when ``sentry_sdk`` is not installed or no
+client is active, so the library has no hard dependency on Sentry.
+"""
+
+import contextlib
+import os
+from collections.abc import Iterator
+from typing import Any
+
+try:
+    import sentry_sdk
+except ImportError:
+    sentry_sdk = None  # ty: ignore[invalid-assignment]
+
+
+def _runtime_environment() -> str | None:
+    """Return the environment the task is executing in, or ``None``.
+
+    ``AWS_LAMBDA_FUNCTION_NAME`` on Lambda, ``AWS_BATCH_JQ_NAME`` (the Batch job
+    queue the job was submitted to) on Batch. ``None`` when neither is present
+    (e.g. local or eager execution).
+    """
+    return os.environ.get("AWS_LAMBDA_FUNCTION_NAME") or os.environ.get(
+        "AWS_BATCH_JQ_NAME"
+    )
+
+
+def _set_metadata(span: Any, *, key: str, value: Any) -> None:
+    """Attach *key*/*value* to *span* using whichever setter the SDK exposes.
+
+    SDK 3.0 (stream mode) spans use ``set_attribute``; SDK 2.x transactions use
+    ``set_tag``. Preferring ``set_attribute`` means the richer, future API is
+    used whenever it is available.
+    """
+    if hasattr(span, "set_attribute"):
+        span.set_attribute(key, value)
+    else:
+        span.set_tag(key, value)
+
+
+def _start_task_root(*, task_name: str) -> Any:
+    """Start and return the per-task span/transaction context manager.
+
+    Crucially, this starts a **child span** when a trace is already active
+    (e.g. ``AwsLambdaIntegration`` starts a transaction per Lambda invocation)
+    and only starts a **new transaction** when nothing is active (e.g. AWS
+    Batch, where there is no Lambda integration).
+
+    Why this matters for volume: starting a nested *transaction* under the
+    invocation transaction produced a *second* transaction per task that
+    inherited — rather than independently re-rolled — the parent's sampling
+    decision, roughly doubling transaction volume and defeating
+    ``traces_sample_rate``. A child span carries no separate sampling decision:
+    it is sent only if its parent transaction is sampled, so one invocation
+    yields one transaction with the task span nested inside it.
+
+    The tracing API also differs across the SDK 2.x → 3.0 boundary:
+
+    * 2.x — ``start_transaction(name=, op=)`` for a root; ``start_span`` for a
+      child of the active transaction.
+    * 3.0 — transactions are gone; ``start_span(name=)`` is both the root (when
+      nothing is active) and a child (when something is), and no longer accepts
+      ``op``.
+    """
+    if not hasattr(sentry_sdk, "start_transaction"):
+        # SDK 3.0: start_span is automatically a root when nothing is active
+        # and a child otherwise — no manual active-trace check needed. (Scope
+        # has no ``transaction`` attribute on 3.0.)
+        return sentry_sdk.start_span(name=task_name)
+    else:
+        # SDK 2.x: a bare start_span with no active transaction is dropped,
+        # so pick child span vs. new transaction based on whether a trace is
+        # already active.
+        has_active_transaction = sentry_sdk.get_current_scope().transaction is not None
+
+        if has_active_transaction:
+            return sentry_sdk.start_span(op="task", name=task_name)
+        else:
+            return sentry_sdk.start_transaction(name=task_name, op="task")
+
+
+def capture_task_exception() -> None:
+    """Report the exception currently being handled to Sentry.
+
+    The executor catches task exceptions (recording a ``FAILED`` TaskRecord)
+    rather than re-raising, so the exception never propagates to an integration
+    that would report it. This matters most on SDK 3.0 (stream mode), where a
+    caught exception produces no error event at all — on 2.x the exception
+    happened to still be reported as it passed through the active span. Calling
+    this on the terminal failure path gives consistent error reporting on both
+    SDK versions.
+
+    Must be called from within an ``except`` block while the task's
+    :func:`task_scope` is still active, so the error carries the task name and
+    tags. A no-op when ``sentry_sdk`` is unavailable or uninitialised.
+    """
+    if sentry_sdk and sentry_sdk.is_initialized():
+        sentry_sdk.capture_exception()
+
+
+@contextlib.contextmanager
+def task_scope(*, task_name: str, message_id: str, n_retries: int) -> Iterator[None]:
+    """Run the enclosed task body inside a per-task Sentry trace.
+
+    Opens an isolated scope and traces the task — as a child span of the active
+    invocation transaction on Lambda, or as its own root transaction when
+    nothing is active (Batch). Records ``lambda_task``, ``lambda_task.message_id``,
+    ``lambda_task.n_retries`` and (when derivable) ``lambda_task.runtime`` as
+    both span metadata and scope tags, so errors are attributed to the task even
+    when the trace is not sampled.
+
+    The scope is isolated via ``new_scope`` so records processed one after
+    another in the same Lambda invocation do not leak their task name into one
+    another.
+
+    A no-op when ``sentry_sdk`` is unavailable or uninitialised.
+    """
+    if not (sentry_sdk and sentry_sdk.is_initialized()):
+        yield
+        return
+
+    runtime = _runtime_environment()
+
+    with sentry_sdk.new_scope() as scope:
+        # Attribute error events and the trace to the task via tags/attributes.
+        # We deliberately do NOT call scope.set_transaction_name(task_name):
+        # on Lambda the task runs inside the invocation transaction, and
+        # renaming it (a) fights across sibling records in a batch and (b) on
+        # SDK 3.0 stream mode corrupts the root-segment naming. The
+        # ``lambda_task`` tag below is the reliable, version-independent
+        # attribution; the task span itself is named after the task.
+        scope.set_tag("lambda_task", task_name)
+        scope.set_tag("lambda_task.message_id", message_id)
+        scope.set_tag("lambda_task.n_retries", n_retries)
+        if runtime:
+            scope.set_tag("lambda_task.runtime", runtime)
+
+        with _start_task_root(task_name=task_name) as span:
+            _set_metadata(span, key="lambda_task", value=task_name)
+            _set_metadata(span, key="lambda_task.message_id", value=message_id)
+            _set_metadata(span, key="lambda_task.n_retries", value=n_retries)
+            if runtime:
+                _set_metadata(span, key="lambda_task.runtime", value=runtime)
+
+            yield

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.1}/pyproject.toml

@@ -7,7 +7,7 @@ packages = ["lambda_tasks"]
 
 [project]
 name = "django-lambda-tasks"
-version = "0.11.0"
+version = "0.11.1"
 description = "Run async tasks in a lambda function"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,7 +31,7 @@ dev = [
     "pytest-cov",
     "ty",
     "psycopg",
-    "sentry-sdk",
+    "sentry-sdk>=2,<3",
 ]
 
 [tool.ty.rules]