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

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

@@ -315,29 +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 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.
+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 traces the task. Trace shape depends on whether a trace is already active:
+`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:
 
-- **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` = 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 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.
+Error attribution also relies on the `lambda_task` **tag**, so it is reliable even when the trace is not sampled.
+
+**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` 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 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.
+**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:** 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.
+**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:** `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.
+**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 `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.
+`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.1 → 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 + capture_task_exception — per-task trace, tags, failure reporting
+│   ├── 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 + `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
+- `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.1 → 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` | `>=2,<3` | Testing the Sentry integration (`task_scope`, `capture_task_exception`); verified against 2.74 and 3.0.0b4. 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.1 → django_lambda_tasks-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-lambda-tasks
-Version: 0.11.1
+Version: 0.11.2
 Summary: Run async tasks in a lambda function
 Requires-Python: >=3.11
 Requires-Dist: awslambdaric
@@ -446,48 +446,57 @@ fields @timestamp, @message
 
 ### Sentry
 
-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.
+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.
 
-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):
+#### 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(),
-        # 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),
     ],
+    disabled_integrations=[
+        AwsLambdaIntegration(),
+    ],
     traces_sample_rate=0.1,
 )
 ```
 
-#### What the library does per task
+Two deliberate choices:
 
-When a task runs, `execute_immediately()` opens an isolated Sentry scope and traces the task:
+- **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.
 
-- **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.
+#### What the library does per task
 
-Either way it records, as both span metadata and scope tags:
+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`). This is also the task span's name.
+- `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 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).
+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. 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 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
 
-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.
+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.
 
 #### SDK version compatibility
 

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

@@ -434,48 +434,57 @@ fields @timestamp, @message
 
 ### Sentry
 
-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.
+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.
 
-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):
+#### 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(),
-        # 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),
     ],
+    disabled_integrations=[
+        AwsLambdaIntegration(),
+    ],
     traces_sample_rate=0.1,
 )
 ```
 
-#### What the library does per task
+Two deliberate choices:
 
-When a task runs, `execute_immediately()` opens an isolated Sentry scope and traces the task:
+- **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.
 
-- **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.
+#### What the library does per task
 
-Either way it records, as both span metadata and scope tags:
+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`). This is also the task span's name.
+- `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 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).
+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. 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 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
 
-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.
+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.
 
 #### SDK version compatibility
 

{django_lambda_tasks-0.11.1 → 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.1 → 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.1 → 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.1 → 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()

{django_lambda_tasks-0.11.1 → django_lambda_tasks-0.11.2}/lambda_tasks/sentry.py

@@ -120,23 +120,38 @@ def _start_task_root(*, task_name: str) -> Any:
             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.
+def handler_error_scope(
+    *, message_id: str | None = None
+) -> "contextlib.AbstractContextManager[Any]":
+    """Scope a handler-level failure's tags so a subsequent error *log* carries them.
+
+    Pre-execution failures in the Lambda/Batch handler (malformed message,
+    un-importable task, misconfiguration, cold-start errors) happen outside any
+    task scope. The handler logs them at ERROR; with the host's
+    ``LoggingIntegration(event_level=ERROR)`` that log becomes the Sentry event.
+    Entering this context first tags an isolated scope so the resulting event is
+    distinguishable (``lambda_task.handler_error``) and carries the message id.
+
+    Usage::
+
+        with handler_error_scope(message_id=...):
+            logger.error("...", exc_info=True)
+
+    A no-op (returns a null context) when ``sentry_sdk`` is unavailable or
+    uninitialised.
     """
-    if sentry_sdk and sentry_sdk.is_initialized():
-        sentry_sdk.capture_exception()
+    if not (sentry_sdk and sentry_sdk.is_initialized()):
+        return contextlib.nullcontext()
+
+    @contextlib.contextmanager
+    def _scope() -> Iterator[None]:
+        with sentry_sdk.new_scope() as scope:
+            scope.set_tag("lambda_task.handler_error", True)
+            if message_id is not None:
+                scope.set_tag("lambda_task.message_id", message_id)
+            yield
+
+    return _scope()
 
 
 @contextlib.contextmanager

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

@@ -7,7 +7,7 @@ packages = ["lambda_tasks"]
 
 [project]
 name = "django-lambda-tasks"
-version = "0.11.1"
+version = "0.11.2"
 description = "Run async tasks in a lambda function"
 readme = "README.md"
 requires-python = ">=3.11"