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

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

@@ -31,7 +31,6 @@ Key modules:
 - `models.py` — `TaskRecord` (Django ORM), `SQSLambdaTaskMessage` (SQS schema + execution), `SQSLambdaTask` (routing + SQS publish, Batch submit, or local pool submit)
 - `local_executor.py` — `ProcessPoolExecutor`-based async local execution for development
 - `handler.py` — AWS Lambda entry point + AWS Batch container entry point (`main()`)
-- `tracing.py` — optional OpenTelemetry tracing (import-time setup, direct X-Ray OTLP export, SigV4-signed)
 - `logging.py` — `task_logger` for invocation-scoped log output
 - `settings.py` — lazy `LambdaTasksSettings` reading from Django settings, queue type helpers
 
@@ -128,7 +127,7 @@ class SQSLambdaTaskMessage(BaseModel):
 
 ## Execution
 
-`SQSLambdaTaskMessage.execute_immediately(*, message_id: str)` in `models.py`:
+`SQSLambdaTaskMessage.execute_immediately(*, message_id: str)` in `models.py` sets the `task_logger` `message_id` and enters `task_scope(...)` (Sentry transaction name + tags), then delegates the run to the private `_run(*, message_id)` method which:
 1. Checks for an existing `TaskRecord` with the same `pk` (`message_id`) via `get_or_create`
 2. If a record already exists (any status), logs and returns immediately — duplicate deliveries are silently skipped
 3. Resolves timeouts: decorator default → settings defaults (soft=270s, hard=300s), validated against queue max (900 for SQS, 3600 for Batch)
@@ -159,7 +158,6 @@ class SQSLambdaTaskMessage(BaseModel):
 - Reads `LAMBDA_TASKS_MESSAGE` env var (the serialized task JSON, set by `submit_batch_job` via container overrides)
 - Uses `AWS_BATCH_JOB_ID` as the `message_id` (falls back to UUID4 if not set)
 - Constructs a synthetic SQS event and delegates to `handler()` — reuses the full cold-start and execution path
-- Before returning, force-flushes and shuts down the global `TracerProvider` (if OTEL tracing is configured) so short-lived Batch jobs do not drop buffered spans
 - Returns exit code 0 on success, 1 on failure
 
 ## Environment Loader
@@ -299,26 +297,6 @@ Relying on `atexit` alone loses this race in applications with a heavy shutdown
 
 The checks are registered via `AppConfig.ready()` and tagged with `deploy=True` so they only fire during `--deploy` checks.
 
-## OpenTelemetry Tracing (optional)
-
-`lambda_tasks/tracing.py` adds OpenTelemetry tracing to the Lambda and Batch execution paths without the managed ADOT Lambda layer — the OTEL packages installed in the application image are the single source of instrumentation (reproducible-build friendly).
-
-Setup lives in the handler module, **not** Django settings. `AwsLambdaInstrumentor` must wrap the handler named by `_HANDLER`/`ORIG_HANDLER` **before** the runtime invokes it, which is earlier than the cold-start `django.setup()` inside `handler()`. So `lambda_tasks.handler` calls `configure_tracing()` and `instrument_lambda_handler()` at **import time**, and the setup is driven purely by standard OTEL environment variables (settings are not configured yet at import time).
-
-Behaviour:
-- Gated on `OTEL_EXPORTER_OTLP_ENDPOINT` (or the per-signal `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`). Unset → everything is a no-op (local dev, tests, un-opted-in deployments).
-- Builds a `TracerProvider` with an OTLP/HTTP span exporter via a `BatchSpanProcessor`. Spans go **directly** to the AWS X-Ray OTLP traces endpoint (`https://xray.<region>.amazonaws.com/v1/traces`) — no collector, no daemon, no Lambda layer.
-- The exporter's `requests` session SigV4-signs each export with the ambient AWS credentials (task / execution role) via `botocore` — no API key to manage. Unsigned when no credentials are resolvable.
-- Uses the AWS X-Ray id generator (`AwsXRayIdGenerator`) so the X-Ray backend accepts the trace IDs, and the X-Ray propagator (`AwsXRayLambdaPropagator` on Lambda, else `AwsXRayPropagator`). The X-Ray packages (`opentelemetry-sdk-extension-aws`, `opentelemetry-propagator-aws-xray`) are part of the `otel` extra.
-- Library instrumentation: after the provider and propagator are installed, `configure_tracing()` calls `_instrument_libraries()`, which attaches the instrumentors for the libraries the tasks use — **psycopg 3** (SQL queries), **botocore** (every boto3 / aioboto3 call), **requests** and **httpx** (outbound HTTP), and **redis** (cache ops via `django_redis` → `redis-py`). Each instrumentor is wrapped independently and is best-effort: a missing or failing one is logged and skipped, never raised, so one broken package cannot stop the others or take down the worker. These are process-global and idempotent, and emit spans into the global provider (so it must exist first). Django request instrumentation (`DjangoInstrumentor`) is **not** installed here — a task has no Django request; the API (ECS) consumer installs that itself. sqlcommenter (`enable_commenter=True` on the psycopg instrumentor) is left off because it modifies the SQL text sent to PostgreSQL.
-- Exporter self-trace suppression: the OTLP exporter POSTs spans over `requests` to the X-Ray endpoint, so the `requests` instrumentor is configured with `excluded_urls="xray\\..*\\.amazonaws\\.com"` to avoid tracing its own export calls (self-referential noise). The instrumentor also honours the `OTEL_PYTHON_REQUESTS_EXCLUDED_URLS` env var for per-environment overrides. botocore is not used by the exporter, so it needs no exclusion.
-- The OpenTelemetry / `requests` imports are **deferred into the functions** (module scope imports only `os`), so the OTEL packages remain a genuinely optional extra: importing `lambda_tasks.handler` with them uninstalled is a no-op, not an `ImportError`. The disabled path (endpoint unset) never reaches any OTEL import.
-- Lambda path: also calls `AwsLambdaInstrumentor().instrument()` (only when `AWS_LAMBDA_FUNCTION_NAME` is set). Batch path (`main()`): the instrumentor is skipped (no handler to wrap); the provider alone is configured.
-- Flush on shutdown: `main()` calls `TracerProvider.force_flush()` / `shutdown()` before the one-shot process exits so short-lived Batch jobs do not drop buffered spans. The Lambda path needs no manual flush — `AwsLambdaInstrumentor` force-flushes per invocation.
-- Best-effort and observable: tracing must never take down the worker. `configure_tracing()` and `instrument_lambda_handler()` catch setup failures (missing OTEL packages, provider build errors) and log a warning instead of raising — important because they run at the handler module's import time. The `lambda_tasks.tracing` logger also surfaces otherwise-silent conditions at `INFO`/`WARNING`: tracing configured / already configured / disabled, handler instrumented or skipped (not on Lambda), no resolvable AWS region, and no resolvable AWS credentials (which would make exports unsigned and rejected by X-Ray).
-
-`configure_tracing()` returns the installed provider (or `None` when disabled or already configured — it is idempotent). Install the OTEL packages via the `otel` extra; the consuming application sets `OTEL_EXPORTER_OTLP_ENDPOINT` and declares the X-Ray packages it wants.
-
 ## Logging
 
 Import `task_logger` to emit log records that are automatically prefixed with the active `message_id`:
@@ -335,6 +313,24 @@ def my_task(*, user_id: int) -> None:
 
 `task_logger` is a `LoggerAdapter` wrapping the `lambda_tasks.task` logger. The executor sets the `message_id` before each task runs and clears it in a `finally` block. Using your own `logging.getLogger(__name__)` is fine — those records just won't carry the prefix.
 
+## 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.
+
+`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:
+
+- transaction/span **name** = the fully-qualified task name (e.g. `myapp.tasks.my_task`)
+- `lambda_task` = task 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
+
+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.
+
+**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.
+
+`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.
+
 ## Built-in Tasks
 
 `lambda_tasks.tasks` provides maintenance tasks that ship with the library:

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

@@ -16,6 +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
 │   ├── models.py               # TaskRecord, SQSLambdaTaskMessage, SQSLambdaTask
 │   ├── settings.py             # LambdaTasksSettings, constants, queue type helpers
 │   ├── secret_loader.py        # Resolves LAMBDA_TASKS_SECRET_* env vars at cold start
@@ -23,7 +24,6 @@ django-lambda-tasks/
 │   ├── local_executor.py        # ProcessPoolExecutor for async local task execution
 │   ├── tasks.py                # Built-in tasks (cleanup_task_records, submit_batch_job)
 │   ├── timeouts.py             # TimeoutContext implementation
-│   ├── tracing.py              # Optional OpenTelemetry tracing (import-time setup, X-Ray OTLP export)
 │   └── migrations/             # Django migrations for TaskRecord
 ├── tests/                      # pytest test suite
 │   ├── conftest.py
@@ -42,13 +42,13 @@ django-lambda-tasks/
 ## Module Responsibilities
 
 - `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), `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`)
+- `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`. At **import time** (before any invocation) it calls `configure_tracing()` and `instrument_lambda_handler()` from `tracing.py` so the Lambda instrumentor can wrap the handler before the runtime invokes it. 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, delegates to `handler()`, then force-flushes and shuts down the global `TracerProvider` (if any) before the one-shot process exits
-- `tracing.py` — optional OpenTelemetry tracing, driven purely by standard OTEL env vars (no Django settings) so the package stays generic; no-op unless `OTEL_EXPORTER_OTLP_ENDPOINT` (or `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`) is set. All OpenTelemetry / `requests` imports are **deferred into the functions** (only `os` is imported at module scope) so the OTEL packages are a genuinely optional extra — importing `lambda_tasks.handler` without them is a no-op, not an `ImportError`. `configure_tracing()` installs a global `TracerProvider` using the X-Ray id generator (`AwsXRayIdGenerator`) with an OTLP/HTTP exporter whose `requests` session SigV4-signs each export to the AWS X-Ray traces endpoint (unsigned when no credentials resolve), and sets the X-Ray propagator (`AwsXRayLambdaPropagator` on Lambda, else `AwsXRayPropagator`), then calls `_instrument_libraries()` to attach the library instrumentors (psycopg 3, botocore, requests, httpx, redis) — each wrapped independently and best-effort (a missing or failing instrumentor is logged, not raised), and the `requests` instrumentor is given an `excluded_urls` regex for the X-Ray OTLP endpoint so the exporter's own export POSTs are not self-traced. `instrument_lambda_handler()` calls `AwsLambdaInstrumentor().instrument()` only when tracing is enabled and `AWS_LAMBDA_FUNCTION_NAME` is set (Lambda path); skipped on the Batch path. `flush_tracing()` force-flushes and shuts down the provider (gated; used by the Batch entry point)
+- `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()`
 - `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`
 - `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.9.2 → django_lambda_tasks-0.11.0}/.kiro/steering/tech.md

@@ -17,30 +17,13 @@ inclusion: always
 | `boto3` | `>= 1.42.69` | AWS SDK — SQS publishing, Lambda integration |
 | `pydantic` | `>= 2.12.5` | Task argument serialization via `SQSLambdaTaskMessage` model |
 
-## Optional Dependencies
-
-Installed via the `otel` extra (`pip install django-lambda-tasks[otel]`). Enables OpenTelemetry tracing in `lambda_tasks/tracing.py`; the library stays generic without them. SigV4 signing reuses `botocore` (already a boto3 transitive dependency) — no extra signing package.
-
-| Package | Purpose |
-|---|---|
-| `opentelemetry-sdk` | `TracerProvider`, `BatchSpanProcessor` |
-| `opentelemetry-exporter-otlp-proto-http` | OTLP/HTTP span exporter (no gRPC, no meta-package) |
-| `opentelemetry-instrumentation-aws-lambda` | Wraps the Lambda handler (`AwsLambdaInstrumentor`) |
-| `opentelemetry-sdk-extension-aws` | X-Ray id generator (`AwsXRayIdGenerator`) |
-| `opentelemetry-propagator-aws-xray` | X-Ray trace propagator |
-| `opentelemetry-instrumentation-psycopg` | SQL query spans (psycopg 3) |
-| `opentelemetry-instrumentation-botocore` | AWS SDK spans — every boto3 / aioboto3 call |
-| `opentelemetry-instrumentation-requests` | Outbound HTTP spans via `requests` |
-| `opentelemetry-instrumentation-httpx` | Outbound HTTP spans via `httpx` |
-| `opentelemetry-instrumentation-redis` | Cache operation spans (`django_redis` → `redis-py`) |
-| `requests` | OTLP/HTTP transport session (SigV4-signed via `botocore`) |
-
 ## Dev Dependencies
 
 | Package | Version | Purpose |
 |---|---|---|
 | `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 |
 
 ## Package Manager
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-lambda-tasks
-Version: 0.9.2
+Version: 0.11.0
 Summary: Run async tasks in a lambda function
 Requires-Python: >=3.11
 Requires-Dist: awslambdaric
@@ -8,18 +8,6 @@ Requires-Dist: boto3
 Requires-Dist: django
 Requires-Dist: pydantic
 Requires-Dist: redis
-Provides-Extra: otel
-Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'otel'
-Requires-Dist: opentelemetry-instrumentation-aws-lambda; extra == 'otel'
-Requires-Dist: opentelemetry-instrumentation-botocore; extra == 'otel'
-Requires-Dist: opentelemetry-instrumentation-httpx; extra == 'otel'
-Requires-Dist: opentelemetry-instrumentation-psycopg; extra == 'otel'
-Requires-Dist: opentelemetry-instrumentation-redis; extra == 'otel'
-Requires-Dist: opentelemetry-instrumentation-requests; extra == 'otel'
-Requires-Dist: opentelemetry-propagator-aws-xray; extra == 'otel'
-Requires-Dist: opentelemetry-sdk; extra == 'otel'
-Requires-Dist: opentelemetry-sdk-extension-aws; extra == 'otel'
-Requires-Dist: requests; extra == 'otel'
 Description-Content-Type: text/markdown
 
 # Django Lambda Tasks
@@ -456,6 +444,32 @@ fields @timestamp, @message
 | sort @timestamp asc
 ```
 
+### 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.
+
+You do **not** need to add a custom integration or change your `sentry_sdk.init(...)`. Keep your existing setup:
+
+```python
+sentry_sdk.init(
+    dsn=SENTRY_DSN,
+    integrations=[DjangoIntegration(), AwsLambdaIntegration()],
+    # ...
+)
+```
+
+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:
+
+- 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).
+
+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.
+
+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.
+
+`sentry_sdk` is not a dependency of this library — if it is not installed or not initialised, the enrichment is a silent no-op.
+
 ---
 
 ## Automatic retries

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

@@ -432,6 +432,32 @@ fields @timestamp, @message
 | sort @timestamp asc
 ```
 
+### 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.
+
+You do **not** need to add a custom integration or change your `sentry_sdk.init(...)`. Keep your existing setup:
+
+```python
+sentry_sdk.init(
+    dsn=SENTRY_DSN,
+    integrations=[DjangoIntegration(), AwsLambdaIntegration()],
+    # ...
+)
+```
+
+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:
+
+- 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).
+
+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.
+
+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.
+
+`sentry_sdk` is not a dependency of this library — if it is not installed or not initialised, the enrichment is a silent no-op.
+
 ---
 
 ## Automatic retries

django_lambda_tasks-0.11.0/example/example_app/tasks.py

@@ -0,0 +1,31 @@
+from time import sleep
+
+from lambda_tasks.decorators import lambda_task
+from lambda_tasks.logging import task_logger
+
+
+@lambda_task()
+def greet(*, name: str) -> str:
+    """A successful task — produces one per-task Sentry transaction named
+    ``example_app.tasks.greet``."""
+    task_logger.info(f"Running greet with: {name=}")
+
+    for ii in range(3):
+        task_logger.info(f"Sleeping: {ii=}")
+        sleep(1)
+
+    try:
+        raise RuntimeError("testing")
+    except Exception:
+        task_logger.error("Raising", exc_info=True)
+
+    return f"Hello, {name}!"
+
+
+@lambda_task()
+def boom(*, name: str) -> str:
+    """A failing task — the executor records it as a FAILED TaskRecord and the
+    error is reported to Sentry attributed to ``example_app.tasks.boom`` (not
+    the Lambda function name), inside its own per-task trace."""
+    task_logger.info(f"Running boom with: {name=}")
+    raise RuntimeError(f"boom for {name}")

django_lambda_tasks-0.11.0/example/example_app/urls.py

@@ -0,0 +1,7 @@
+from django.urls import path
+from example_app.views import trigger, trigger_error
+
+urlpatterns = [
+    path("trigger/", trigger),
+    path("trigger-error/", trigger_error),
+]

django_lambda_tasks-0.11.0/example/example_app/views.py

@@ -0,0 +1,17 @@
+from django.http import HttpRequest, HttpResponse
+from example_app.tasks import boom, greet
+
+
+def trigger(request: HttpRequest) -> HttpResponse:
+    """Enqueue the successful task — produces a per-task Sentry transaction."""
+    name = request.GET.get("name", "world")
+    greet.execute_on_commit(name=name)
+    return HttpResponse(f"greet task triggered for: {name}")
+
+
+def trigger_error(request: HttpRequest) -> HttpResponse:
+    """Enqueue the failing task — produces a Sentry error attributed to the
+    task name, inside its own per-task trace."""
+    name = request.GET.get("name", "world")
+    boom.execute_on_commit(name=name)
+    return HttpResponse(f"boom task triggered for: {name}")

django_lambda_tasks-0.11.0/example/example_project/sentry.py

@@ -0,0 +1,50 @@
+"""Optional Sentry initialisation for the example app.
+
+Demonstrates how a host application wires Sentry so that
+``django-lambda-tasks`` can attribute per-task traces and errors. This mirrors
+a typical production ``sentry_sdk.init(...)`` (Django + AWS Lambda integrations
+and tracing), but is driven entirely by environment variables so the example
+runs with or without Sentry configured.
+
+``init_sentry()`` is called from ``settings.py`` at import time. Because the
+local process-pool workers call ``django.setup()`` (which imports settings) in
+each child process, this runs in the web process *and* in every task worker —
+which is exactly what is needed for the per-task trace to be captured where the
+task actually executes.
+"""
+
+import logging
+import os
+
+
+def init_sentry() -> None:
+    """Initialise Sentry if ``SENTRY_DSN`` is set; otherwise do nothing.
+
+    Idempotent enough for the example's purposes: ``sentry_sdk.init`` is safe to
+    call once per process, and this is only invoked from settings import.
+    """
+    dsn = os.environ.get("SENTRY_DSN")
+    if not dsn:
+        return
+
+    import sentry_sdk
+    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=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=logging.ERROR),
+        ],
+        # 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.9.2 → django_lambda_tasks-0.11.0}/example/example_project/settings.py

@@ -88,3 +88,10 @@ LOGGING = {
         "level": "INFO",
     },
 }
+
+# Optional Sentry integration — set SENTRY_DSN to enable. Initialised here (at
+# settings import) so it also runs inside each local process-pool worker, which
+# imports settings via django.setup(). See example_project/sentry.py.
+from example_project.sentry import init_sentry  # noqa: E402
+
+init_sentry()

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

@@ -26,11 +26,6 @@ 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.tracing import (
-    configure_tracing,
-    flush_tracing,
-    instrument_lambda_handler,
-)
 
 logger = logging.getLogger(__name__)
 
@@ -174,25 +169,11 @@ def main() -> int:
         context=None,
     )
 
-    # Flush any buffered spans before the one-shot process exits (no-op unless
-    # tracing is enabled — this never imports OTEL otherwise).
-    flush_tracing()
-
     if result["batchItemFailures"]:
         return 1
     else:
         return 0
 
 
-# Initialise tracing at import time so the Lambda instrumentor can wrap the
-# handler before the runtime invokes it (which is earlier than the cold-start
-# django.setup() inside handler()). This MUST run after `handler` and `main`
-# are defined: wrapt resolves the handler by attribute lookup on this module,
-# and wrapping a name that does not exist yet raises AttributeError. No-op
-# unless OTEL_EXPORTER_OTLP_ENDPOINT is set.
-configure_tracing()
-instrument_lambda_handler()
-
-
 if __name__ == "__main__":
     sys.exit(main())