feat(pipeline): complete the async HttpTracer lifecycle with AsyncOperationTracingPolicy

The async pipeline already emitted attempt-level HttpTracer events
(AsyncRetryPolicy's attempt_started/attempt_failed and AsyncRedirectPolicy's
request_url_resolved) but never the operation lifecycle, so an async operator
saw attempts and redirect hops with no operation_started bracket and no final
operation_succeeded/operation_failed. The per-operation lifecycle had been
extracted into the sync-only OperationTracingPolicy without an async
counterpart, leaving the async tracer stream permanently incomplete.

The HttpTracer callbacks are synchronous and transport-agnostic by contract, so
there is no async barrier to emitting them — only a missing policy.

- Add AsyncOperationTracingPolicy (async twin of OperationTracingPolicy) at the
  outermost Stage.OPERATION; it awaits only the downstream send.
- Wire it as the outermost policy in default_async_pipeline and export it from
  pipeline.policies.
- Cover it: the lifecycle fires exactly once and reflects the final outcome
  across async retry (success-after-failure and exhaustion) and redirect
  (success and late-hop failure), the tracing-disabled path, and the default
  async stack wiring.
- Regenerate the public API surface baseline.
- Correct the docs that described the async stack as carrying no tracing
  (CHANGELOG, README, CLAUDE.md, tracing module docstring): only the
  per-attempt OpenTelemetry span policy and structured logging remain sync-only.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: OmarAlJarrah

CHANGELOG.md

@@ -41,13 +41,16 @@ Changed).
 - **Client-identity policy** (`pipeline.policies.client_identity`, plus its
   async twin). Sets a consistent `User-Agent` / client-identity header derived
   from the configured application id and SDK version.
-- **Per-operation tracing policy** (`OperationTracingPolicy` in
-  `pipeline.policies.tracing_policy`, with a new outermost `Stage.OPERATION`).
-  Emits the per-operation `HttpTracer` lifecycle (`operation_started`, then
-  exactly one `operation_succeeded` / `operation_failed`) from outside the retry
-  and redirect wrappers, so the reported outcome reflects the final result of
-  the whole call rather than a single attempt or hop. Sync-only, in line with
-  the rest of the tracing stack; the async pipeline carries no tracing.
+- **Per-operation tracing policy** (`OperationTracingPolicy` and its async twin
+  `AsyncOperationTracingPolicy`, with a new outermost `Stage.OPERATION`). Emits
+  the per-operation `HttpTracer` lifecycle (`operation_started`, then exactly
+  one `operation_succeeded` / `operation_failed`) from outside the retry and
+  redirect wrappers, so the reported outcome reflects the final result of the
+  whole call rather than a single attempt or hop. Both `default_pipeline` and
+  `default_async_pipeline` wire it, so the async stack now reports the same
+  lifecycle alongside the attempt-level events its retry / redirect policies
+  already emit. Only `TracingPolicy`'s per-attempt OpenTelemetry span policy
+  remains sync-only.
 - **HTTP tracer** (`instrumentation.http_tracer`). An adapter-style tracer base
   whose per-event methods default to no-ops, so a subclass overrides only the
   events it cares about. Wired through the tracing policy for span emission.
@@ -153,9 +156,11 @@ The following were intentionally left out of this round and are **not** included
   errors themselves.
 - **`sendfile` fast-path** — file bodies are streamed via the existing
   `iter_bytes` path; no zero-copy `sendfile` transport optimisation was added.
-- **Async tracing / logging** — the tracing and logging policies (including the
-  new `OperationTracingPolicy`) ship sync-only; `default_async_pipeline` carries
-  no tracing, and async callers handle per-operation observability themselves.
+- **Async OpenTelemetry spans / logging** — the per-attempt span policy
+  (`TracingPolicy`) and `LoggingPolicy` ship sync-only, so
+  `default_async_pipeline` emits the per-operation `HttpTracer` lifecycle and
+  attempt-level events but no OpenTelemetry spans or structured request /
+  response logs.
 - **MCP support** — no Model Context Protocol integration is included.
 - **Java SDK items** — the Java counterpart lives in a separate repository and
   was out of scope here.

CLAUDE.md

@@ -132,7 +132,7 @@ python-sdk/
     │   │   │   │
     │   │   │   ├── policies/               # redirect, idempotency, retry, set_date,
     │   │   │   │                           # client_identity, logging, tracing
-    │   │   │   │                           # (async twins only for the first five)
+    │   │   │   │                           # (async twins for all but logging and per-attempt tracing)
     │   │   │   └── step/                   # PipelineStep, StepMetadata
     │   │   ├── client/                     # HttpClient + AsyncHttpClient Protocols
     │   │   ├── config/                     # Configuration
@@ -207,13 +207,14 @@ Layered, bottom-up:
    `Pipeline` / `AsyncPipeline` run an ordered set of policies grouped into
    `Stage`s via `StagedPipelineBuilder`. Shipped policies: redirect,
    idempotency, retry, set-date, client-identity, logging, tracing, and
-   operation-tracing. Async twins under `pipeline/policies/` exist only for
-   redirect, idempotency, retry, set-date, and client-identity; logging,
-   tracing, and operation-tracing are sync-only.
+   operation-tracing. Async twins exist for redirect, idempotency, retry,
+   set-date, client-identity, and operation-tracing; logging and the
+   per-attempt tracing policy are sync-only.
    `default_pipeline()` / `default_async_pipeline()` assemble the standard
    stack in the order operation-tracing → redirect → idempotency → retry →
    set-date → client-identity → [auth] → logging → tracing (the async
-   pipeline omits the tracing and logging policies). The lower-level
+   pipeline keeps operation-tracing but omits logging and the per-attempt
+   tracing span). The lower-level
    `pipeline/step/PipelineStep` Protocol (`(input, context) -> output`) plus
    `StepMetadata` remain for custom composition.
 5. **`client/HttpClient`** — single-method Protocol

README.md

@@ -176,7 +176,7 @@ Bottom-up, the layers are:
 | `http.webhooks`     | `WebhookVerifier`, `InvalidWebhookSignatureError` — HMAC signature verification with timestamp tolerance  |
 | `pagination`        | `Page`, `Paginator` / `AsyncPaginator`, `PaginationStrategy` (`CursorStrategy`, `PageNumberStrategy`, `LinkHeaderStrategy`) |
 | `pipeline`          | `Pipeline`, `AsyncPipeline`, `Policy` ABC, `Stage` enum, `StagedPipelineBuilder`, `default_pipeline()`   |
-| `pipeline.policies` | `RedirectPolicy`, `IdempotencyPolicy`, `RetryPolicy`, `SetDatePolicy`, `ClientIdentityPolicy`, `LoggingPolicy`, `OperationTracingPolicy`, `TracingPolicy` (async twins for all but logging/tracing) |
+| `pipeline.policies` | `RedirectPolicy`, `IdempotencyPolicy`, `RetryPolicy`, `SetDatePolicy`, `ClientIdentityPolicy`, `LoggingPolicy`, `OperationTracingPolicy`, `TracingPolicy` (async twins for all but `LoggingPolicy` and `TracingPolicy`) |
 | `client`            | `HttpClient` and `AsyncHttpClient` Protocols                                                             |
 | `serde`             | `Serde`, `Serializer`, `Deserializer` Protocols + `JsonSerde` reference impl                             |
 | `instrumentation`   | `ClientLogger`, `UrlRedactor`, `Tracer`, `Span`, `InstrumentationContext`, `contextvars` correlation helpers, noop singletons |

packages/dexpace-sdk-core/src/dexpace/sdk/core/pipeline/defaults.py

@@ -13,6 +13,7 @@
 from .policies.async_redirect import AsyncRedirectPolicy
 from .policies.async_retry import AsyncRetryPolicy
 from .policies.async_set_date import AsyncSetDatePolicy
+from .policies.async_tracing_policy import AsyncOperationTracingPolicy
 from .policies.client_identity import ClientIdentityPolicy
 from .policies.idempotency import IdempotencyPolicy
 from .policies.logging_policy import LoggingPolicy
@@ -106,11 +107,19 @@ def default_async_pipeline(
 ) -> AsyncStagedPipelineBuilder:
     """Async twin of `default_pipeline`.
 
-    Mirrors the sync version's stack minus logging/tracing, which currently
-    only ship as sync policies. Async-side observability lives on the caller's
-    side until async versions land.
+    Mirrors the sync version's stack. `AsyncOperationTracingPolicy` brackets
+    the whole operation from the outermost stage so the per-operation
+    ``HttpTracer`` lifecycle (``operation_started`` / ``operation_succeeded`` /
+    ``operation_failed``) fires once and reflects the final outcome — completing
+    the attempt-level events the async retry and redirect policies already emit
+    through the same per-operation tracer. The per-attempt OpenTelemetry span
+    policy (`TracingPolicy`) and `LoggingPolicy` ship sync-only, so the async
+    stack omits those two.
     """
     builder = AsyncStagedPipelineBuilder(client)
+    # Sorts to Stage.OPERATION (outermost), bracketing every hop / attempt so
+    # the per-operation lifecycle fires once on the final outcome.
+    builder.append(AsyncOperationTracingPolicy())
     builder.append(redirect or AsyncRedirectPolicy())
     builder.append(idempotency or AsyncIdempotencyPolicy())
     builder.append(retry or AsyncRetryPolicy())

packages/dexpace-sdk-core/src/dexpace/sdk/core/pipeline/policies/__init__.py

@@ -11,6 +11,7 @@
 from .async_redirect import AsyncRedirectPolicy
 from .async_retry import AsyncRetryPolicy
 from .async_set_date import AsyncSetDatePolicy
+from .async_tracing_policy import AsyncOperationTracingPolicy
 from .client_identity import ClientIdentityPolicy, default_user_agent
 from .idempotency import IdempotencyPolicy
 from .logging_policy import LoggingPolicy
@@ -22,6 +23,7 @@
 __all__ = [
     "AsyncClientIdentityPolicy",
     "AsyncIdempotencyPolicy",
+    "AsyncOperationTracingPolicy",
     "AsyncRedirectPolicy",
     "AsyncRetryPolicy",
     "AsyncSetDatePolicy",

packages/dexpace-sdk-core/src/dexpace/sdk/core/pipeline/policies/async_tracing_policy.py

@@ -0,0 +1,72 @@
+# Copyright (c) 2026 dexpace and Omar Aljarrah.
+# Licensed under the MIT License. See LICENSE.md in the repository root for details.
+
+"""Async twin of `OperationTracingPolicy`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Literal
+
+from ..async_policy import AsyncPolicy
+from ..stage import Stage
+from .redirect import resolve_http_tracer
+
+if TYPE_CHECKING:
+    from ...http.request.request import Request
+    from ...http.response.async_response import AsyncResponse
+    from ..context import PipelineContext
+
+
+class AsyncOperationTracingPolicy(AsyncPolicy):
+    """Async variant of `OperationTracingPolicy`.
+
+    Emits the per-operation ``HttpTracer`` lifecycle around the whole async
+    call. Placed at `Stage.OPERATION`, outside the redirect and retry wrappers,
+    so its single ``send`` brackets every hop and attempt: it emits
+    ``operation_started`` before dispatching the chain and exactly one of
+    ``operation_succeeded`` / ``operation_failed`` once the chain unwinds, so
+    the operation outcome reflects what the caller observes rather than the
+    result of the first attempt.
+
+    This completes the async ``HttpTracer`` lifecycle. `AsyncRetryPolicy` and
+    `AsyncRedirectPolicy` already emit the attempt-level events and
+    ``request_url_resolved`` through the same per-operation tracer (resolved
+    via ``resolve_http_tracer`` and cached in ``ctx.data``), so without this
+    policy the async stack reports attempts but never the operation outcome.
+    The tracer callbacks are synchronous, so the body matches the sync twin
+    apart from the ``await`` on the downstream send.
+
+    Disable per-call by setting ``ctx.options["tracing_enabled"] = False``.
+
+    Attributes:
+        STAGE: Pinned to `Stage.OPERATION` at the type level so mis-slotting is
+            caught by ``mypy``.
+    """
+
+    STAGE: ClassVar[Literal[Stage.OPERATION]] = Stage.OPERATION
+    __slots__ = ()
+
+    async def send(self, request: Request, ctx: PipelineContext) -> AsyncResponse:
+        """Bracket the downstream chain with the per-operation lifecycle.
+
+        Args:
+            request: Outgoing request.
+            ctx: Pipeline context, forwarded unchanged.
+
+        Returns:
+            The response from the downstream chain.
+        """
+        if not ctx.options.get("tracing_enabled", True):
+            return await self.next.send(request, ctx)
+        http_tracer = resolve_http_tracer(ctx)
+        http_tracer.operation_started()
+        try:
+            response = await self.next.send(request, ctx)
+        except BaseException as err:
+            http_tracer.operation_failed(err)
+            raise
+        http_tracer.operation_succeeded()
+        return response
+
+
+__all__ = ["AsyncOperationTracingPolicy"]

packages/dexpace-sdk-core/src/dexpace/sdk/core/pipeline/policies/tracing_policy.py

@@ -30,9 +30,10 @@
 the sentinel trace ids. Disable either per-call by setting
 ``ctx.options["tracing_enabled"] = False``.
 
-Both policies are sync-only, in line with the rest of the tracing and logging
-stack; ``default_async_pipeline`` carries no tracing, so async callers own
-per-operation observability on their side.
+`OperationTracingPolicy` has an async twin, `AsyncOperationTracingPolicy`,
+wired into ``default_async_pipeline`` so the async stack reports the same
+per-operation lifecycle. `TracingPolicy`'s per-attempt OpenTelemetry span
+machinery is sync-only and has no async counterpart.
 """
 
 from __future__ import annotations

packages/dexpace-sdk-core/tests/pipeline/test_defaults.py

@@ -126,3 +126,14 @@ def test_default_async_pipeline_returns_builder() -> None:
 def test_default_async_pipeline_builds_async_pipeline() -> None:
     pipeline = default_async_pipeline(_AsyncStubTransport()).build()
     assert isinstance(pipeline, AsyncPipeline)
+
+
+def test_default_async_pipeline_wires_operation_tracing() -> None:
+    from dexpace.sdk.core.pipeline.policies import AsyncOperationTracingPolicy
+
+    builder = default_async_pipeline(_AsyncStubTransport())
+    # Mirrors the sync default: the per-operation lifecycle policy occupies the
+    # outermost OPERATION pillar, so async callers get the same
+    # operation_started / operation_succeeded / operation_failed bracket around
+    # the attempt-level events the retry/redirect policies already emit.
+    assert isinstance(builder._pillars[Stage.OPERATION], AsyncOperationTracingPolicy)