django-lambda-tasks 0.8.1__tar.gz → 0.9.1__tar.gz

django_lambda_tasks-0.9.1/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "pre-commit"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      pre-commit:
+        patterns:
+          - "*"

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/.github/workflows/ci.yml

@@ -6,7 +6,7 @@ on:
   workflow_call:
 
 env:
-  MINIMUM_PYTHON_VERSION: '3.10'
+  MINIMUM_PYTHON_VERSION: '3.11'
 
 concurrency:
   group: ${{ github.head_ref || github.run_id }}
@@ -17,9 +17,9 @@ jobs:
   precommit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           python-version: ${{ env.MINIMUM_PYTHON_VERSION }}
       - name: Run static code inspections
@@ -29,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
     services:
       postgres:
         image: postgres:17
@@ -45,9 +45,9 @@ jobs:
           --health-timeout 5s
           --health-retries 5
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install uv and set the python version
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           python-version: ${{ matrix.python-version }}
       - name: Run tests

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/.github/workflows/release.yml

@@ -6,7 +6,7 @@ on:
       - published
 
 env:
-  MINIMUM_PYTHON_VERSION: '3.10'
+  MINIMUM_PYTHON_VERSION: '3.11'
 
 jobs:
   ci:
@@ -18,15 +18,15 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install Python ${{ env.MINIMUM_PYTHON_VERSION }}
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           python-version: ${{ env.MINIMUM_PYTHON_VERSION }}
       - name: Build the package
         run: uv build
       - name: 'Upload Artifact'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: python-dist
           path: dist/
@@ -43,9 +43,9 @@ jobs:
       id-token: write
     steps:
     - name: Download build artifacts
-      uses: actions/download-artifact@v4
+      uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
       with:
         name: python-dist
         path: dist
     - name: Publish package distributions
-      uses: pypa/gh-action-pypi-publish@release/v1
+      uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/.kiro/steering/product.md

@@ -31,6 +31,7 @@ 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
 
@@ -158,6 +159,7 @@ 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
@@ -297,6 +299,24 @@ 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.
+- 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`:

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/.kiro/steering/structure.md

@@ -23,6 +23,7 @@ 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
@@ -43,7 +44,8 @@ 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), `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`. 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`). `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)
 - `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

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/.kiro/steering/tech.md

@@ -17,6 +17,19 @@ 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 |
+| `requests` | OTLP/HTTP transport session (SigV4-signed via `botocore`) |
+
 ## Dev Dependencies
 
 | Package | Version | Purpose |

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
     - repo: https://github.com/adamchainz/django-upgrade
-      rev: 1.30.0
+      rev: 1.33.0
       hooks:
           - id: django-upgrade
             args: [--target-version, "5.2"]
@@ -13,17 +13,17 @@ repos:
           - id: mixed-line-ending
           - id: trailing-whitespace
     - repo: https://github.com/pycqa/isort
-      rev: 8.0.1
+      rev: 9.0.2
       hooks:
           - id: isort
     - repo: https://github.com/asottile/pyupgrade
-      rev: v3.21.2
+      rev: v3.22.0
       hooks:
           - id: pyupgrade
             language: python
-            args: [--py310-plus]
+            args: [--py311-plus]
     - repo: https://github.com/ambv/black
-      rev: 26.3.1
+      rev: 26.10.1
       hooks:
           - id: black
             language: python

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/PKG-INFO

@@ -1,13 +1,25 @@
 Metadata-Version: 2.5
 Name: django-lambda-tasks
-Version: 0.8.1
+Version: 0.9.1
 Summary: Run async tasks in a lambda function
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: awslambdaric
 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

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/lambda_tasks/handler.py

@@ -26,9 +26,21 @@ 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__)
 
+# Initialise tracing at import time so the Lambda instrumentor can wrap the
+# handler before the first invocation (which is earlier than the cold-start
+# django.setup() inside handler()). No-op unless OTEL_EXPORTER_OTLP_ENDPOINT
+# is set.
+configure_tracing()
+instrument_lambda_handler()
+
 _cold_start_done: bool = False
 
 
@@ -169,10 +181,14 @@ 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
-
-    return 0
+    else:
+        return 0
 
 
 if __name__ == "__main__":

django_lambda_tasks-0.9.1/lambda_tasks/tracing.py

@@ -0,0 +1,318 @@
+"""Optional OpenTelemetry tracing for the Lambda and Batch execution paths.
+
+Initialised at import time of ``lambda_tasks.handler`` (before the Lambda
+runtime invokes the handler, which is earlier than ``django.setup()``). Driven
+entirely by standard OTEL environment variables so this package stays generic:
+the consuming application declares the OTEL dependencies and sets
+``OTEL_EXPORTER_OTLP_ENDPOINT`` to the regional AWS X-Ray OTLP traces endpoint
+(``https://xray.<region>.amazonaws.com/v1/traces``).
+
+Spans are exported directly to the X-Ray endpoint — no collector, no daemon,
+no Lambda layer. Requests are SigV4-signed with the ambient AWS credentials
+(the task / execution role), so there is no API key to manage. When no
+credentials are resolvable (local dev / tests) the request is left unsigned.
+
+The OpenTelemetry and ``requests`` imports are deferred into the functions
+below so they are only reached when tracing is enabled (a non-empty
+``OTEL_EXPORTER_OTLP_ENDPOINT`` / ``OTEL_EXPORTER_OTLP_TRACES_ENDPOINT``).
+This keeps the OTEL packages a genuinely optional extra: importing
+``lambda_tasks.handler`` without them installed is a no-op, not an
+``ImportError``.
+"""
+
+import logging
+import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import requests
+    from opentelemetry.sdk.trace import TracerProvider
+
+logger = logging.getLogger(__name__)
+
+_XRAY_SIGV4_SERVICE_NAME = "xray"
+
+
+def tracing_is_enabled() -> bool:
+    """Whether an OTLP traces endpoint has been configured.
+
+    Either the base ``OTEL_EXPORTER_OTLP_ENDPOINT`` or the per-signal
+    ``OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`` turns it on.
+    """
+    return bool(
+        os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "").strip()
+        or os.environ.get("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "").strip()
+    )
+
+
+def _running_on_lambda() -> bool:
+    return bool(os.environ.get("AWS_LAMBDA_FUNCTION_NAME"))
+
+
+def _build_signing_session() -> "requests.Session":
+    import requests
+    import requests.auth
+    from botocore.auth import SigV4Auth
+    from botocore.awsrequest import AWSRequest
+    from botocore.session import Session as BotocoreSession
+
+    class _SigV4Auth(requests.auth.AuthBase):
+        """SigV4-signs OTLP exports to the X-Ray endpoint."""
+
+        def __init__(
+            self, *, service_name: str, region: str, session: BotocoreSession
+        ) -> None:
+            self._service_name = service_name
+            self._region = region
+            self._session = session
+
+        def __call__(self, r: "requests.PreparedRequest") -> "requests.PreparedRequest":
+            credentials = self._session.get_credentials()
+
+            if credentials is None:
+                logger.warning(
+                    "No AWS credentials resolvable; sending OTLP span export to "
+                    "%s unsigned. The X-Ray endpoint will reject unsigned "
+                    "requests, so spans will be dropped.",
+                    r.url,
+                )
+                return r
+
+            aws_request = AWSRequest(
+                method=r.method,
+                url=r.url,
+                data=r.body,
+                headers={"Content-Type": "application/x-protobuf"},
+            )
+            SigV4Auth(credentials, self._service_name, self._region).add_auth(
+                aws_request
+            )
+
+            r.headers.update(dict(aws_request.headers))
+
+            return r
+
+    region = os.environ.get("AWS_REGION", os.environ.get("AWS_DEFAULT_REGION", ""))
+
+    if not region:
+        logger.warning(
+            "No AWS region resolvable from AWS_REGION / AWS_DEFAULT_REGION; "
+            "SigV4 signing of OTLP span exports may fail."
+        )
+
+    session = requests.Session()
+    session.auth = _SigV4Auth(
+        service_name=_XRAY_SIGV4_SERVICE_NAME,
+        region=region,
+        session=BotocoreSession(),
+    )
+
+    return session
+
+
+def _build_tracer_provider() -> "TracerProvider":
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+        OTLPSpanExporter,
+    )
+    from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    service_name = os.environ.get(
+        "OTEL_SERVICE_NAME",
+        os.environ.get("AWS_LAMBDA_FUNCTION_NAME", "lambda-tasks"),
+    )
+
+    tracer_provider = TracerProvider(
+        resource=Resource.create(attributes={"service.name": service_name}),
+        id_generator=AwsXRayIdGenerator(),
+    )
+
+    tracer_provider.add_span_processor(
+        BatchSpanProcessor(
+            span_exporter=OTLPSpanExporter(session=_build_signing_session())
+        )
+    )
+    return tracer_provider
+
+
+def _set_xray_propagator() -> None:
+    from opentelemetry import propagate
+    from opentelemetry.propagators.aws import (
+        AwsXRayLambdaPropagator,
+        AwsXRayPropagator,
+    )
+
+    propagate.set_global_textmap(
+        AwsXRayLambdaPropagator() if _running_on_lambda() else AwsXRayPropagator()
+    )
+
+
+def _instrument_libraries() -> None:
+    """Instrument the libraries whose calls we want as spans.
+
+    SQL (psycopg 3), AWS SDK (botocore → boto3/aioboto3), outbound HTTP
+    (requests and httpx), and cache (redis). Each is wrapped independently and
+    is best-effort: a missing or failing instrumentor is logged, not raised, so
+    it cannot take down the worker. All are process-global and idempotent.
+
+    The OTLP span export itself goes out over ``requests`` to the X-Ray
+    endpoint; that URL is excluded from the requests instrumentor so the
+    exporter's own calls are not traced (which would be self-referential noise).
+    """
+
+    def _try(name: str, instrument: "Callable[[], None]") -> None:
+        try:
+            instrument()
+        except Exception:
+            logger.warning(
+                "Failed to instrument %s for tracing; continuing without it.",
+                name,
+                exc_info=True,
+            )
+        else:
+            logger.info("%s instrumentation installed.", name)
+
+    def _psycopg() -> None:
+        from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
+
+        PsycopgInstrumentor().instrument()
+
+    def _botocore() -> None:
+        from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
+
+        BotocoreInstrumentor().instrument()
+
+    def _requests() -> None:
+        from opentelemetry.instrumentation.requests import RequestsInstrumentor
+
+        # Do not trace the exporter's own POST to the X-Ray OTLP endpoint.
+        RequestsInstrumentor().instrument(excluded_urls="xray\\..*\\.amazonaws\\.com")
+
+    def _httpx() -> None:
+        from opentelemetry.instrumentation.httpx import (
+            HTTPXClientInstrumentor,
+        )
+
+        HTTPXClientInstrumentor().instrument()
+
+    def _redis() -> None:
+        from opentelemetry.instrumentation.redis import RedisInstrumentor
+
+        RedisInstrumentor().instrument()
+
+    _try("psycopg", _psycopg)
+    _try("botocore", _botocore)
+    _try("requests", _requests)
+    _try("httpx", _httpx)
+    _try("redis", _redis)
+
+
+def configure_tracing() -> "TracerProvider | None":
+    """Install the global tracer provider. No-op unless enabled.
+
+    Returns the provider so callers (e.g. the Batch entry point) can flush it
+    on shutdown, or ``None`` when tracing is disabled or already configured.
+
+    Tracing is best-effort: if it is enabled but the OTEL packages are missing
+    or the provider cannot be built, the failure is logged and ``None`` is
+    returned rather than propagated — a broken observability setup must not
+    take down the worker (this runs at import time of the handler module).
+    """
+    if not tracing_is_enabled():
+        logger.debug("OTEL tracing disabled (no OTLP endpoint configured).")
+        return None
+
+    try:
+        from opentelemetry import trace
+        from opentelemetry.sdk.trace import TracerProvider
+
+        if isinstance(trace.get_tracer_provider(), TracerProvider):
+            logger.info(
+                "A TracerProvider is already installed; skipping configuration."
+            )
+            return None
+
+        tracer_provider = _build_tracer_provider()
+        trace.set_tracer_provider(tracer_provider)
+        _set_xray_propagator()
+        _instrument_libraries()
+    except ImportError:
+        logger.warning(
+            "OTEL tracing is enabled but the OpenTelemetry packages are not "
+            "installed; tracing is disabled. Install the 'otel' extra to "
+            "enable it.",
+            exc_info=True,
+        )
+        return None
+    except Exception:
+        logger.warning(
+            "Failed to configure OTEL tracing; continuing without it.",
+            exc_info=True,
+        )
+        return None
+
+    logger.info("OTEL tracing configured (exporting spans to the OTLP endpoint).")
+    return tracer_provider
+
+
+def instrument_lambda_handler() -> None:
+    """Wrap the Lambda handler for tracing. No-op unless enabled.
+
+    Must be called at import time of the handler module, before the runtime
+    invokes the handler.
+    """
+    if not tracing_is_enabled():
+        return
+
+    if not _running_on_lambda():
+        logger.debug(
+            "Not running on Lambda (AWS_LAMBDA_FUNCTION_NAME unset); "
+            "skipping AwsLambdaInstrumentor."
+        )
+        return
+
+    try:
+        from opentelemetry.instrumentation.aws_lambda import (
+            AwsLambdaInstrumentor,
+        )
+
+        AwsLambdaInstrumentor().instrument()
+    except Exception:
+        logger.warning(
+            "Failed to instrument the Lambda handler for tracing; "
+            "continuing without handler spans.",
+            exc_info=True,
+        )
+        return
+
+    logger.info("AwsLambdaInstrumentor installed; Lambda handler is traced.")
+
+
+def flush_tracing() -> None:
+    """Force-flush and shut down the global tracer provider. No-op unless enabled.
+
+    Called at the end of the one-shot Batch entry point so short-lived jobs do
+    not drop buffered spans. Gated on ``tracing_is_enabled()`` so the OTEL
+    imports are never reached when tracing is disabled (or the packages are not
+    installed).
+    """
+    if not tracing_is_enabled():
+        return
+
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+
+    provider = trace.get_tracer_provider()
+    if isinstance(provider, TracerProvider):
+        logger.debug("Flushing and shutting down the TracerProvider before exit.")
+        provider.force_flush()
+        provider.shutdown()
+    else:
+        logger.debug(
+            "Tracing is enabled but no TracerProvider is installed; "
+            "nothing to flush."
+        )

{django_lambda_tasks-0.8.1 → django_lambda_tasks-0.9.1}/pyproject.toml

@@ -7,10 +7,10 @@ packages = ["lambda_tasks"]
 
 [project]
 name = "django-lambda-tasks"
-version = "0.8.1"
+version = "0.9.1"
 description = "Run async tasks in a lambda function"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
     "boto3",
     "django",
@@ -19,6 +19,21 @@ dependencies = [
     "awslambdaric",
 ]
 
+[project.optional-dependencies]
+otel = [
+    "requests",
+    "opentelemetry-sdk",
+    "opentelemetry-exporter-otlp-proto-http",
+    "opentelemetry-instrumentation-aws-lambda",
+    "opentelemetry-sdk-extension-aws",
+    "opentelemetry-propagator-aws-xray",
+    "opentelemetry-instrumentation-psycopg",
+    "opentelemetry-instrumentation-botocore",
+    "opentelemetry-instrumentation-requests",
+    "opentelemetry-instrumentation-httpx",
+    "opentelemetry-instrumentation-redis",
+]
+
 [dependency-groups]
 dev = [
     "hypothesis",
@@ -31,6 +46,8 @@ dev = [
     "pytest-cov",
     "ty",
     "psycopg",
+    "httpx",
+    "django-lambda-tasks[otel]",
 ]
 
 [tool.ty.rules]