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

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.2}/.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.2}/.kiro/steering/product.md

@@ -315,21 +315,30 @@ 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. The **recommended** host configuration is `DjangoIntegration` + `LoggingIntegration(event_level=logging.ERROR)`, and **without** `AwsLambdaIntegration`. `AwsLambdaIntegration` names every event's transaction after the Lambda function, which hides which task ran; omitting it lets each task be traced under its own task-named transaction.
 
-`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)` does the per-task tracing. `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. With `AwsLambdaIntegration` removed there is no invocation transaction competing for the name, so on **both** Lambda and Batch the task starts its **own transaction named after the task**. It records, both on the span and as scope tags:
 
-- transaction/span **name** = the fully-qualified task name (e.g. `myapp.tasks.my_task`)
-- `lambda_task` = task name
+- `lambda_task` = fully-qualified task name (e.g. `myapp.tasks.my_task`) — also the transaction/span 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
 
-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 attribution also relies on the `lambda_task` **tag**, so it is reliable even when the trace is not sampled.
 
-**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.
+**If a host keeps `AwsLambdaIntegration` anyway:** the library still behaves correctly. `_start_task_root` detects the active invocation transaction (via `sentry_sdk.get_current_scope().transaction` on 2.x; on 3.0 `start_span` is automatically root-or-child) and traces the task as a **child span** of it rather than a second, competing transaction. A nested *transaction* per task would inherit (not independently re-roll) the invocation's sampling decision, doubling transaction volume and defeating `traces_sample_rate`; a child span is sent only if its parent is sampled. In that case the transaction name is the Lambda function name and the task name lives on the `lambda_task` tag.
 
-`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` deliberately does **not** call `scope.set_transaction_name(task_name)`: when an invocation transaction is active it would rename the shared transaction (fighting across sibling records in a batch) and, on SDK 3.0 stream mode, corrupt the root-segment naming. The `lambda_task` tag is the reliable, version-independent attribution.
+
+**Reporting task failures:** the executor catches task exceptions (recording `FAILED` and not re-raising). On the two **terminal** failure branches in `models.py` (plain failure and max-retries-exceeded) it logs the exception at ERROR via `task_logger.error(error, exc_info=True)`. With the assumed host config `LoggingIntegration(event_level=logging.ERROR)`, that log becomes a Sentry event, attributed to the task by the active `task_scope` tags. No explicit `capture_exception` call is made — the error log is the single reporting path, so there are no duplicate events. The **retry** branch logs at WARNING and is deliberately not reported — transient, to-be-re-enqueued failures would flood Sentry; only terminal failures are reported.
+
+**Reporting failures outside a task:** pre-execution failures in the handler (malformed SQS message, un-importable task, misconfiguration, cold-start errors) happen before `task_scope` opens. `handler.py` logs them at ERROR inside `lambda_tasks.sentry.handler_error_scope(message_id=...)`, a context manager that tags an isolated scope (`lambda_task.handler_error` + the message id) so the resulting log-driven Sentry event is identifiable. This relies on the same `LoggingIntegration(event_level=ERROR)` as task failures. Cold-start failures are additionally re-raised so AWS marks the invocation failed and redrives.
+
+**Error-level log forwarding (required):** both task-failure and handler-failure reporting flow through `logger.error(..., exc_info=True)` + the host's `LoggingIntegration(event_level=logging.ERROR)`. On sentry-sdk 2.x `event_level=ERROR` was the default; on 3.0 the default is `None`, so the host **must** configure it explicitly for error reporting to work (it is part of the recommended config and the example app). The library does not call `capture_exception` itself, so this integration is not optional for error visibility.
+
+**SDK version compatibility:** the integration 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` and `handler_error_scope` 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; a dedicated CI job additionally runs the suite against the latest sentry-sdk 3.x pre-release on Python 3.14.
 
 ## Built-in Tasks
 

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.2}/.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 + handler_error_scope — per-task trace, tags, failure attribution
 │   ├── models.py               # TaskRecord, SQSLambdaTaskMessage, SQSLambdaTask
 │   ├── settings.py             # LambdaTasksSettings, constants, queue type helpers
 │   ├── secret_loader.py        # Resolves LAMBDA_TASKS_SECRET_* env vars at cold start
@@ -44,11 +44,11 @@ django-lambda-tasks/
 - `decorators.py` — defines `LambdaTaskWrapper` and `@lambda_task` decorator factory; enforces kwargs-only at decoration time; validates timeouts (> 0, soft < hard) at decoration time; upper-bound timeout validation deferred to execution time based on queue type
 - `models.py` — `TaskRecord` (Django ORM), `SQSLambdaTaskMessage` (Pydantic, SQS schema + execution logic; `execute_immediately` owns the logging + Sentry context and delegates the run to a private `_run` method), `SQSLambdaTask` (Pydantic, holds message + routing; `_execute()` inspects queue config to publish to SQS, submit to Batch via `submit_batch_job`, execute eagerly, or submit to the local process pool; `execute_on_commit()` registers `_execute` with `transaction.on_commit`)
 - `local_executor.py` — `ProcessPoolExecutor`-based async local execution; `get_pool()` lazily creates a module-level pool; `submit_task()` fire-and-forget submission; `_execute_in_worker()` deserializes and runs the task in a child process; `_pool_initializer()` calls `django.setup()` per worker (and sets `SIGINT` to `SIG_IGN` so workers ignore Ctrl+C); `_install_shutdown_handlers()` installs main-thread `SIGINT`/`SIGTERM` handlers that release the pool before chaining to the previous handler
-- `handler.py` — Lambda entry point (`handler(event, context)`); cold-start init (memory limit → temporary log handler → `resolve_environment()` → `resolve_secrets_into_env()` → handler removed → conditional `django.setup()`) runs inside the handler on first invocation, guarded by `_cold_start_done` sentinel; calls `db.close_old_connections()` before each SQS record to handle stale connections on warm starts; processes SQS records independently; returns `batchItemFailures`. Also provides `main()` as the AWS Batch container entry point (`python -m lambda_tasks.handler`) — reads `LAMBDA_TASKS_MESSAGE` env var, constructs a synthetic SQS event, and delegates to `handler()`
+- `handler.py` — Lambda entry point (`handler(event, context)`); cold-start init (memory limit → temporary log handler → `resolve_environment()` → `resolve_secrets_into_env()` → handler removed → conditional `django.setup()`) runs inside the handler on first invocation, guarded by `_cold_start_done` sentinel; calls `db.close_old_connections()` before each SQS record to handle stale connections on warm starts; processes SQS records independently; returns `batchItemFailures`; logs pre-execution failures (malformed message, import error, misconfiguration) at ERROR inside `handler_error_scope` so the host's `LoggingIntegration` reports them tagged `lambda_task.handler_error`; cold-start failures are reported the same way and re-raised. Also provides `main()` as the AWS Batch container entry point (`python -m lambda_tasks.handler`) — reads `LAMBDA_TASKS_MESSAGE` env var, constructs a synthetic SQS event, and delegates to `handler()`
 - `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 + `handler_error_scope` context manager. `task_scope` opens an isolated `new_scope` and traces the task. With the **recommended** host config (no `AwsLambdaIntegration`) nothing is active, so the task starts its **own transaction named after the task** on both Lambda and Batch. If a host keeps `AwsLambdaIntegration`, the task is instead traced as a **child span** of the active invocation transaction (detected via `sentry_sdk.get_current_scope().transaction` on 2.x; `start_span` is auto root-or-child on 3.0) — never a second, competing transaction, which 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 an active invocation transaction and break 3.0 segment naming); error attribution rides on the `lambda_task` tag. **Failure reporting** is via error logs, not explicit captures: the terminal failure branches in `models.py` (plain failure + max-retries) call `task_logger.error(error, exc_info=True)`, and the host's `LoggingIntegration(event_level=ERROR)` turns that into the Sentry event (the retry branch logs at WARNING and is not reported). `handler_error_scope(message_id=...)` is a context manager used in `handler.py` to tag an isolated scope (`lambda_task.handler_error` + message id) around the handler's `logger.error`, so pre-task failures are reported and identifiable via the same LoggingIntegration. 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`. Error reporting requires `LoggingIntegration(event_level=logging.ERROR)` in the host init (default on 2.x, must be set on 3.0); 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.2}/.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`, `handler_error_scope`); 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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-lambda-tasks
-Version: 0.11.0
+Version: 0.11.2
 Summary: Run async tasks in a lambda function
 Requires-Python: >=3.11
 Requires-Dist: awslambdaric
@@ -446,29 +446,63 @@ 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, and each task is traced under its own task-named transaction.
 
-You do **not** need to add a custom integration or change your `sentry_sdk.init(...)`. Keep your existing setup:
+#### Recommended `sentry_sdk.init(...)`
+
+Use `DjangoIntegration` + `LoggingIntegration(event_level=logging.ERROR)`, and **do not** add `AwsLambdaIntegration`:
 
 ```python
+import logging
+from sentry_sdk.integrations.aws_lambda import AwsLambdaIntegration
+from sentry_sdk.integrations.django import DjangoIntegration
+from sentry_sdk.integrations.logging import LoggingIntegration
+
 sentry_sdk.init(
     dsn=SENTRY_DSN,
-    integrations=[DjangoIntegration(), AwsLambdaIntegration()],
-    # ...
+    integrations=[
+        DjangoIntegration(),
+        LoggingIntegration(event_level=logging.ERROR),
+    ],
+    disabled_integrations=[
+        AwsLambdaIntegration(),
+    ],
+    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:
+Two deliberate choices:
+
+- **No `AwsLambdaIntegration`.** It names every event's transaction after the Lambda function, which hides which task ran — all tasks would look the same. Without it, each task's trace is named after the task (see below). You lose `AwsLambdaIntegration`'s automatic reporting of handler-level failures, but the library reports those itself (see "Failures outside a task"), so nothing is lost in practice.
+- **`LoggingIntegration(event_level=logging.ERROR)`.** This makes `logger.error(...)` (including `task_logger`) become Sentry events. On sentry-sdk 2.x `event_level=ERROR` was the default; on 3.0 the default is `None`, so you must set it explicitly. It is harmless on 2.x.
+
+#### What the library does per task
+
+When a task runs, `execute_immediately()` opens an isolated Sentry scope and traces the task. With `AwsLambdaIntegration` removed there is no invocation transaction competing for the name, so on **both** Lambda and Batch the task starts its **own transaction named after the task**. It records, as both span metadata and scope tags:
+
+- `lambda_task` — the fully-qualified task name (e.g. `myapp.tasks.send_welcome_email`); also the transaction/span 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 also relies on the `lambda_task` **tag**, so it is reliable even when the trace is not sampled.
+
+> If you keep `AwsLambdaIntegration` for other reasons, the library still does the right thing: it detects the active invocation transaction and traces the task as a **child span** of it (rather than a second, competing transaction, which would double trace volume and defeat `traces_sample_rate`). In that case the transaction name is the Lambda function name and the task name lives on the `lambda_task` tag.
+
+#### Task failures are reported
+
+The executor catches a failing task's exception (recording a `FAILED` `TaskRecord`) rather than re-raising it. On the **terminal failure paths** — a plain failure and max-retries-exceeded — the library logs the exception at ERROR (`task_logger.error(..., exc_info=True)`), which your `LoggingIntegration(event_level=ERROR)` turns into a Sentry event, attributed to the task via the active scope tags. This is why that integration is part of the recommended config: without it, a merely-caught exception produces no error event on 3.0.
+
+Transient, retryable failures (a task that will be re-enqueued) are logged at WARNING and **not** reported to Sentry, to avoid flooding on every retry; only the final, terminal failure is reported.
+
+#### Failures outside a task
 
-- 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).
+Pre-execution failures in the Lambda/Batch handler — a malformed SQS message, a task that cannot be imported, a misconfiguration, or a cold-start error — happen before the task scope opens and are caught by the handler. The handler logs them at ERROR inside a `handler_error_scope` that tags the event `lambda_task.handler_error` (plus the message id). With `LoggingIntegration(event_level=ERROR)` that log becomes a single, tagged Sentry event — so you are still alerted even though `AwsLambdaIntegration` is not installed. Cold-start failures are also re-raised so AWS marks the invocation failed and redrives it.
 
-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.2}/README.md

@@ -434,29 +434,63 @@ 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, and each task is traced under its own task-named transaction.
 
-You do **not** need to add a custom integration or change your `sentry_sdk.init(...)`. Keep your existing setup:
+#### Recommended `sentry_sdk.init(...)`
+
+Use `DjangoIntegration` + `LoggingIntegration(event_level=logging.ERROR)`, and **do not** add `AwsLambdaIntegration`:
 
 ```python
+import logging
+from sentry_sdk.integrations.aws_lambda import AwsLambdaIntegration
+from sentry_sdk.integrations.django import DjangoIntegration
+from sentry_sdk.integrations.logging import LoggingIntegration
+
 sentry_sdk.init(
     dsn=SENTRY_DSN,
-    integrations=[DjangoIntegration(), AwsLambdaIntegration()],
-    # ...
+    integrations=[
+        DjangoIntegration(),
+        LoggingIntegration(event_level=logging.ERROR),
+    ],
+    disabled_integrations=[
+        AwsLambdaIntegration(),
+    ],
+    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:
+Two deliberate choices:
+
+- **No `AwsLambdaIntegration`.** It names every event's transaction after the Lambda function, which hides which task ran — all tasks would look the same. Without it, each task's trace is named after the task (see below). You lose `AwsLambdaIntegration`'s automatic reporting of handler-level failures, but the library reports those itself (see "Failures outside a task"), so nothing is lost in practice.
+- **`LoggingIntegration(event_level=logging.ERROR)`.** This makes `logger.error(...)` (including `task_logger`) become Sentry events. On sentry-sdk 2.x `event_level=ERROR` was the default; on 3.0 the default is `None`, so you must set it explicitly. It is harmless on 2.x.
+
+#### What the library does per task
+
+When a task runs, `execute_immediately()` opens an isolated Sentry scope and traces the task. With `AwsLambdaIntegration` removed there is no invocation transaction competing for the name, so on **both** Lambda and Batch the task starts its **own transaction named after the task**. It records, as both span metadata and scope tags:
+
+- `lambda_task` — the fully-qualified task name (e.g. `myapp.tasks.send_welcome_email`); also the transaction/span 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 also relies on the `lambda_task` **tag**, so it is reliable even when the trace is not sampled.
+
+> If you keep `AwsLambdaIntegration` for other reasons, the library still does the right thing: it detects the active invocation transaction and traces the task as a **child span** of it (rather than a second, competing transaction, which would double trace volume and defeat `traces_sample_rate`). In that case the transaction name is the Lambda function name and the task name lives on the `lambda_task` tag.
+
+#### Task failures are reported
+
+The executor catches a failing task's exception (recording a `FAILED` `TaskRecord`) rather than re-raising it. On the **terminal failure paths** — a plain failure and max-retries-exceeded — the library logs the exception at ERROR (`task_logger.error(..., exc_info=True)`), which your `LoggingIntegration(event_level=ERROR)` turns into a Sentry event, attributed to the task via the active scope tags. This is why that integration is part of the recommended config: without it, a merely-caught exception produces no error event on 3.0.
+
+Transient, retryable failures (a task that will be re-enqueued) are logged at WARNING and **not** reported to Sentry, to avoid flooding on every retry; only the final, terminal failure is reported.
+
+#### Failures outside a task
 
-- 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).
+Pre-execution failures in the Lambda/Batch handler — a malformed SQS message, a task that cannot be imported, a misconfiguration, or a cold-start error — happen before the task scope opens and are caught by the handler. The handler logs them at ERROR inside a `handler_error_scope` that tags the event `lambda_task.handler_error` (plus the message id). With `LoggingIntegration(event_level=ERROR)` that log becomes a single, tagged Sentry event — so you are still alerted even though `AwsLambdaIntegration` is not installed. Cold-start failures are also re-raised so AWS marks the invocation failed and redrives it.
 
-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.2}/example/README.md

@@ -47,3 +47,16 @@ The task runs in a background worker process and the response confirms it was tr
 Visit: `http://127.0.0.1:8000/admin/` → Lambda Tasks → Task records
 
 Log in with the superuser credentials you created above.
+
+## Testing the Sentry integration (optional)
+
+Set `SENTRY_DSN` to see per-task traces and error attribution in Sentry. The init lives in `example_project/sentry.py` and uses `DjangoIntegration` + `LoggingIntegration(event_level=ERROR)` **without** `AwsLambdaIntegration`, so each task is traced under its own task-named transaction (see the library README's Sentry section for why).
+
+```bash
+SENTRY_DSN="https://<key>@<org>.ingest.sentry.io/<project>" uv run python manage.py runserver
+```
+
+- `http://127.0.0.1:8000/trigger/?name=Alice` — a successful task; produces a transaction named `example_app.tasks.greet`.
+- `http://127.0.0.1:8000/trigger-error/?name=Bob` — a failing task; produces an error attributed to `example_app.tasks.boom` (via the library's `capture_exception` on the terminal failure path).
+
+Without `SENTRY_DSN` set, Sentry initialisation is skipped and the app runs exactly as above.

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.2}/example/example_project/sentry.py

@@ -36,14 +36,21 @@ def init_sentry() -> None:
         dsn=dsn,
         integrations=[
             DjangoIntegration(),
-            AwsLambdaIntegration(),
-            # On sentry-sdk 2.x the logging integration defaulted to
-            # event_level=ERROR, so logger.error(...) calls (e.g. task_logger)
-            # became Sentry events automatically. On 3.0 the default is None, so
-            # error logs no longer surface as events. Set it explicitly so
-            # task_logger.error output appears in Sentry on both SDK versions.
+            # LoggingIntegration(event_level=ERROR) is REQUIRED, not optional:
+            # the library reports task and handler failures by logging them at
+            # ERROR (not by calling capture_exception), so this integration is
+            # what turns those logs into Sentry events. On sentry-sdk 2.x
+            # event_level=ERROR was the default; on 3.0 the default is None, so
+            # it must be set explicitly.
             LoggingIntegration(event_level=logging.ERROR),
         ],
+        disabled_integrations=[
+            # AwsLambdaIntegration is intentionally omitted. It names every
+            # event's transaction after the Lambda function, which hides the
+            # task name. Without it, each task's trace is named after the task
+            # (see lambda_tasks.sentry).
+            AwsLambdaIntegration(),
+        ],
         # Sample every transaction so the per-task trace is always sent while
         # you are testing. Lower this in a real deployment.
         traces_sample_rate=float(os.environ.get("SENTRY_TRACES_SAMPLE_RATE", "1.0")),

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.2}/lambda_tasks/handler.py

@@ -26,6 +26,7 @@ from django.apps import apps
 
 from lambda_tasks.environment_loader import resolve_environment
 from lambda_tasks.secret_loader import resolve_secrets_into_env
+from lambda_tasks.sentry import handler_error_scope
 
 logger = logging.getLogger(__name__)
 
@@ -124,7 +125,17 @@ def handler(event: dict, context: object) -> dict:
     Returns a partial-batch failure report so AWS only re-drives failed records.
     Signature is fixed by AWS and uses two args only.
     """
-    _perform_cold_start()
+    try:
+        _perform_cold_start()
+    except Exception:
+        # Cold-start failures (secret resolution, django.setup(), memory limit)
+        # escape handler() so the invocation is marked failed and redriven, as
+        # AWS expects. The error log is reported to Sentry by the host's
+        # LoggingIntegration; handler_error_scope tags it as a handler error.
+        # Re-raise to preserve the AWS failure contract.
+        with handler_error_scope():
+            logger.error("Cold-start initialisation failed", exc_info=True)
+        raise
 
     # Local import due to AppRegistryNotReady
     from lambda_tasks.models import SQSLambdaTaskMessage
@@ -138,10 +149,13 @@ def handler(event: dict, context: object) -> dict:
                 record["body"]
             ).execute_immediately(message_id=record["messageId"])
         except Exception:
-            logger.error(
-                "Failed to process SQS record",
-                exc_info=True,
-            )
+            # Pre-execution failures (malformed message, import error,
+            # misconfiguration) happen before execute_immediately opens its
+            # task_scope. The error log is reported to Sentry by the host's
+            # LoggingIntegration; handler_error_scope tags it with the message
+            # id and marks it a handler error.
+            with handler_error_scope(message_id=record.get("messageId")):
+                logger.error("Failed to process SQS record", exc_info=True)
             batch_item_failures.append({"itemIdentifier": record["messageId"]})
 
     return {"batchItemFailures": batch_item_failures}
@@ -154,21 +168,31 @@ def main() -> int:
     constructs a synthetic SQS event, and delegates to handler().
 
     Returns 0 on success, 1 on failure.
+
+    Wrapped in a top-level handler so that failures on the Batch path — a
+    missing message, or an exception escaping cold-start/``handler()`` (e.g.
+    secret resolution or ``django.setup()``) — are reported to Sentry. The
+    Batch container has no AWS-side Sentry integration, so without this such
+    failures would only reach stderr.
     """
     logging.basicConfig(level=logging.INFO)
 
-    message_json = os.environ.get("LAMBDA_TASKS_MESSAGE")
-    if not message_json:
-        logger.error("LAMBDA_TASKS_MESSAGE environment variable is not set.")
+    try:
+        message_json = os.environ.get("LAMBDA_TASKS_MESSAGE")
+        if not message_json:
+            raise RuntimeError("LAMBDA_TASKS_MESSAGE environment variable is not set.")
+
+        message_id = os.environ.get("AWS_BATCH_JOB_ID", str(uuid.uuid4()))
+
+        result = handler(
+            event={"Records": [{"messageId": message_id, "body": message_json}]},
+            context=None,
+        )
+    except Exception:
+        with handler_error_scope(message_id=os.environ.get("AWS_BATCH_JOB_ID")):
+            logger.error("AWS Batch entry point failed", exc_info=True)
         return 1
 
-    message_id = os.environ.get("AWS_BATCH_JOB_ID", str(uuid.uuid4()))
-
-    result = handler(
-        event={"Records": [{"messageId": message_id, "body": message_json}]},
-        context=None,
-    )
-
     if result["batchItemFailures"]:
         return 1
     else:

{django_lambda_tasks-0.11.0 → django_lambda_tasks-0.11.2}/lambda_tasks/models.py

@@ -21,7 +21,7 @@ from redis.exceptions import LockError
 
 from lambda_tasks.local_executor import submit_task
 from lambda_tasks.logging import task_logger
-from lambda_tasks.sentry import capture_task_exception, task_scope
+from lambda_tasks.sentry import task_scope
 from lambda_tasks.settings import (
     MAX_DELAY,
     BatchQueueConfig,
@@ -210,7 +210,8 @@ class SQSLambdaTaskMessage(BaseModel):
             elif effective_retry_on and isinstance(error, effective_retry_on):
                 conf = LambdaTasksSettings()
                 if self.n_retries >= conf.MAX_RETRIES:
-                    capture_task_exception()
+                    task_logger.error("Maximum retries exceeded", exc_info=True)
+
                     record.status = TaskStatus.FAILED
                     record.traceback = traceback.format_exc()
                     record.end_time = now()
@@ -252,7 +253,6 @@ class SQSLambdaTaskMessage(BaseModel):
             else:
                 task_logger.error(error, exc_info=True)
 
-                capture_task_exception()
                 record.status = TaskStatus.FAILED
                 record.traceback = traceback.format_exc()
                 record.end_time = now()