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

{django_lambda_tasks-0.9.1 → django_lambda_tasks-0.10.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
 
@@ -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,24 +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.
-- 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.9.1 → django_lambda_tasks-0.10.0}/.kiro/steering/structure.md

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

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

@@ -17,19 +17,6 @@ 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.9.1 → django_lambda_tasks-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-lambda-tasks
-Version: 0.9.1
+Version: 0.10.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

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

@@ -26,21 +26,9 @@ 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
 
 
@@ -181,10 +169,6 @@ 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:

{django_lambda_tasks-0.9.1 → django_lambda_tasks-0.10.0}/lambda_tasks/tasks.py

@@ -11,7 +11,11 @@ from lambda_tasks.models import SQSLambdaTaskMessage, TaskRecord
 from lambda_tasks.settings import BatchQueueConfig, LambdaTasksSettings
 
 
-@lambda_task
+@lambda_task(
+    singleton=True,
+    # No need to retry here as this should be retried periodically
+    retry_singleton=False,
+)
 def cleanup_task_records(*, retention_days: int = 7) -> int:
     """Delete TaskRecord rows older than ``retention_days``.
 

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

@@ -7,7 +7,7 @@ packages = ["lambda_tasks"]
 
 [project]
 name = "django-lambda-tasks"
-version = "0.9.1"
+version = "0.10.0"
 description = "Run async tasks in a lambda function"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -19,21 +19,6 @@ 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",
@@ -46,8 +31,6 @@ dev = [
     "pytest-cov",
     "ty",
     "psycopg",
-    "httpx",
-    "django-lambda-tasks[otel]",
 ]
 
 [tool.ty.rules]

django_lambda_tasks-0.10.0/tests/test_batch_worker.py

@@ -0,0 +1,77 @@
+"""Tests for lambda_tasks.batch_worker entry point."""
+
+import uuid
+from unittest.mock import patch
+
+import pytest
+
+from lambda_tasks.decorators import lambda_task
+from lambda_tasks.handler import main
+from lambda_tasks.models import SQSLambdaTaskMessage, TaskRecord
+
+
+@pytest.fixture(autouse=True)
+def _patch_close_old_connections():
+    """Prevent close_old_connections from closing the test DB connection."""
+    with patch("lambda_tasks.handler.db.close_old_connections"):
+        yield
+
+
+QUEUES = {
+    "default": {"queue_url": "https://sqs.us-east-1.amazonaws.com/000000000000/default"}
+}
+
+
+# Module-level tasks for import_string resolution
+
+
+@lambda_task
+def _worker_task(*, value: int) -> str:
+    return "ok"
+
+
+def test_missing_env_var_returns_1(monkeypatch):
+    monkeypatch.delenv("LAMBDA_TASKS_MESSAGE", raising=False)
+    assert main() == 1
+
+
+@pytest.mark.django_db
+def test_valid_message_executes_task(monkeypatch, settings):
+    settings.LAMBDA_TASKS_EAGER = True
+    settings.LAMBDA_TASKS_QUEUES = QUEUES
+
+    task_name = f"{_worker_task.__module__}.{_worker_task.__wrapped__.__qualname__}"
+    message = SQSLambdaTaskMessage(task_name=task_name, kwargs={"value": 1})
+    job_id = str(uuid.uuid4())
+
+    monkeypatch.setenv("LAMBDA_TASKS_MESSAGE", message.model_dump_json())
+    monkeypatch.setenv("AWS_BATCH_JOB_ID", job_id)
+
+    result = main()
+
+    assert result == 0
+    record = TaskRecord.objects.get(pk=job_id)
+    assert record.status == TaskRecord.TaskStatus.SUCCEEDED
+
+
+def test_invalid_json_returns_1(monkeypatch):
+    monkeypatch.setenv("LAMBDA_TASKS_MESSAGE", "not-valid-json")
+    monkeypatch.delenv("AWS_BATCH_JOB_ID", raising=False)
+    assert main() == 1
+
+
+@pytest.mark.django_db
+def test_uses_uuid_when_no_batch_job_id(monkeypatch, settings):
+    settings.LAMBDA_TASKS_EAGER = True
+    settings.LAMBDA_TASKS_QUEUES = QUEUES
+
+    task_name = f"{_worker_task.__module__}.{_worker_task.__wrapped__.__qualname__}"
+    message = SQSLambdaTaskMessage(task_name=task_name, kwargs={"value": 5})
+
+    monkeypatch.setenv("LAMBDA_TASKS_MESSAGE", message.model_dump_json())
+    monkeypatch.delenv("AWS_BATCH_JOB_ID", raising=False)
+
+    result = main()
+
+    assert result == 0
+    assert TaskRecord.objects.count() == 1

django_lambda_tasks-0.9.1/lambda_tasks/tracing.py

@@ -1,318 +0,0 @@
-"""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."
-        )