httpware 0.4.0__tar.gz → 0.6.0__tar.gz

{httpware-0.4.0 → httpware-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: httpware
-Version: 0.4.0
+Version: 0.6.0
 Summary: Resilience-first async HTTP client framework for Python
 Keywords: http,async,client,resilience,retry,circuit-breaker,middleware,httpx,pydantic
 Author: Artur Shiriev
@@ -15,14 +15,16 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Framework :: AsyncIO
 Requires-Dist: httpx2>=2.0.0,<3.0
-Requires-Dist: httpware[pydantic,msgspec] ; extra == 'all'
+Requires-Dist: httpware[pydantic,msgspec,otel] ; extra == 'all'
 Requires-Dist: msgspec>=0.18 ; extra == 'msgspec'
+Requires-Dist: opentelemetry-api>=1.20 ; extra == 'otel'
 Requires-Dist: pydantic>=2.0,<3.0 ; extra == 'pydantic'
 Requires-Python: >=3.11, <4
 Project-URL: repository, https://github.com/modern-python/httpware
 Project-URL: docs, https://httpware.readthedocs.io
 Provides-Extra: all
 Provides-Extra: msgspec
+Provides-Extra: otel
 Provides-Extra: pydantic
 Description-Content-Type: text/markdown
 
@@ -37,7 +39,7 @@ Description-Content-Type: text/markdown
 
 `httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
-> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0. Streaming and observability are not yet shipped.
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
 ## Install
 
@@ -45,7 +47,7 @@ Description-Content-Type: text/markdown
 pip install httpware                # core only — no decoder
 pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
 pip install httpware[msgspec]       # + MsgspecDecoder
-pip install httpware[all]           # everything declared above (pydantic, msgspec)
+pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
 ```
 
 `AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
@@ -89,10 +91,51 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
+### Streaming responses
+
+For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+`stream()` auto-raises `StatusError` subclasses on 4xx/5xx with the response body pre-read, so `exc.response.content` is accessible from the caught exception.
+
+It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any custom middleware are bypassed. (Retry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
+
 ## Errors
 
 All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.
 
+## Observability
+
+`Retry` and `Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
+
+Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
+
+```python
+import logging
+
+# Enable visibility into retry / bulkhead operational events
+logging.getLogger("httpware.retry").setLevel(logging.WARNING)
+logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
+```
+
+For OTel attribute enrichment on the active span — install the extra:
+
+```bash
+pip install httpware[otel]
+```
+
+When installed, `_emit_event` calls `trace.get_current_span().add_event(name, attributes=...)` automatically. We never create our own spans; for HTTP-level tracing install `opentelemetry-instrumentation-httpx` separately.
+
 ## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
 
 ## 📦 [PyPI](https://pypi.org/project/httpware)

{httpware-0.4.0 → httpware-0.6.0}/README.md

@@ -9,7 +9,7 @@
 
 `httpware` is a thin opinionated wrapper around `httpx2`. It re-exports `httpx2.Request`/`httpx2.Response`, adds a middleware chain composed at client construction, supports opt-in typed response decoding (pydantic and msgspec are both extras), and raises a status-keyed exception tree automatically on 4xx/5xx. It also ships a small resilience suite — `Retry` middleware with a Finagle-style `RetryBudget`, plus a `Bulkhead` concurrency limiter — under `httpware.middleware.resilience`.
 
-> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0. Streaming and observability are not yet shipped.
+> **Status:** Pre-1.0. Public API is subject to change between minor releases until v1.0.
 
 ## Install
 
@@ -17,7 +17,7 @@
 pip install httpware                # core only — no decoder
 pip install httpware[pydantic]      # + PydanticDecoder (the default-decoder path)
 pip install httpware[msgspec]       # + MsgspecDecoder
-pip install httpware[all]           # everything declared above (pydantic, msgspec)
+pip install httpware[all]           # everything declared above (pydantic, msgspec, otel)
 ```
 
 `AsyncClient()` with no `decoder=` argument defaults to constructing a `PydanticDecoder`; that path requires the `pydantic` extra and raises `ImportError` at `AsyncClient.__init__` if it is missing.
@@ -61,10 +61,51 @@ async def main() -> None:
         user = await client.get("/users/1", response_model=User)
 ```
 
+### Streaming responses
+
+For large responses or server-sent events, stream the body chunk-by-chunk. `stream()` is an async context manager:
+
+```python
+from httpware import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient(base_url="https://api.example.com") as client:
+        async with client.stream("GET", "/big-file") as response:
+            async for chunk in response.aiter_bytes():
+                process(chunk)
+```
+
+`stream()` auto-raises `StatusError` subclasses on 4xx/5xx with the response body pre-read, so `exc.response.content` is accessible from the caught exception.
+
+It does NOT pass through the middleware chain: `Retry`, `Bulkhead`, and any custom middleware are bypassed. (Retry separately refuses to retry any request — stream or non-stream — whose body was an async-iterable, since streams can't replay across attempts.)
+
 ## Errors
 
 All 4xx/5xx responses raise typed exceptions automatically: `NotFoundError`, `ServiceUnavailableError`, `RateLimitedError`, etc. — all subclasses of `httpware.StatusError`. Transport-layer transient failures raise `NetworkError`; the resilience middleware raise `RetryBudgetExhaustedError` and `BulkheadFullError`. Everything inherits `httpware.ClientError`.
 
+## Observability
+
+`Retry` and `Bulkhead` emit operational events via two channels — stdlib `logging` records (always on) and OpenTelemetry span events (when `opentelemetry-api` is installed).
+
+Logger names (`httpware.retry`, `httpware.bulkhead`) and event names (`retry.giving_up`, `retry.budget_refused`, `retry.streaming_refused`, `bulkhead.rejected`) are the stable public contract.
+
+```python
+import logging
+
+# Enable visibility into retry / bulkhead operational events
+logging.getLogger("httpware.retry").setLevel(logging.WARNING)
+logging.getLogger("httpware.bulkhead").setLevel(logging.WARNING)
+```
+
+For OTel attribute enrichment on the active span — install the extra:
+
+```bash
+pip install httpware[otel]
+```
+
+When installed, `_emit_event` calls `trace.get_current_span().add_event(name, attributes=...)` automatically. We never create our own spans; for HTTP-level tracing install `opentelemetry-instrumentation-httpx` separately.
+
 ## 🗒️ [Release notes](https://github.com/modern-python/httpware/releases)
 
 ## 📦 [PyPI](https://pypi.org/project/httpware)

{httpware-0.4.0 → httpware-0.6.0}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Framework :: AsyncIO",
 ]
-version = "0.4.0"
+version = "0.6.0"
 dependencies = [
     "httpx2>=2.0.0,<3.0",
 ]
@@ -34,7 +34,8 @@ dependencies = [
 [project.optional-dependencies]
 pydantic = ["pydantic>=2.0,<3.0"]
 msgspec = ["msgspec>=0.18"]
-all = ["httpware[pydantic,msgspec]"]
+otel = ["opentelemetry-api>=1.20"]
+all = ["httpware[pydantic,msgspec,otel]"]
 
 [project.urls]
 repository = "https://github.com/modern-python/httpware"

{httpware-0.4.0 → httpware-0.6.0}/src/httpware/_internal/import_checker.py

@@ -5,3 +5,4 @@ from importlib.util import find_spec
 
 is_msgspec_installed = find_spec("msgspec") is not None
 is_pydantic_installed = find_spec("pydantic") is not None
+is_otel_installed = find_spec("opentelemetry") is not None

httpware-0.6.0/src/httpware/_internal/observability.py

@@ -0,0 +1,42 @@
+"""Observability emission helper — structured logging + opt-in OpenTelemetry span events.
+
+See planning/specs/2026-06-05-observability-design.md for the contract.
+
+Logger names (``httpware.retry``, ``httpware.bulkhead``) and event names
+(``retry.giving_up``, ``bulkhead.rejected``, etc.) are the public observability
+surface. They are stable: renames are breaking changes.
+"""
+
+import logging
+import typing
+
+from httpware._internal import import_checker
+
+
+def _emit_event(
+    logger: logging.Logger,
+    event_name: str,
+    *,
+    level: int,
+    message: str,
+    attributes: dict[str, typing.Any],
+) -> None:
+    """Emit one observability event to both channels.
+
+    1. Always emits a structured log record at ``level`` with ``extra=attributes``
+       (so log aggregators that index ``extra`` see structured fields).
+    2. If ``opentelemetry-api`` is installed, calls
+       ``trace.get_current_span().add_event(event_name, attributes=attributes)``.
+       When no tracer is active, ``get_current_span()`` returns a ``NonRecordingSpan``
+       whose ``add_event`` is a documented no-op — so the call is unconditional
+       behind the install gate.
+
+    The lazy ``from opentelemetry import trace`` inside the if-block preserves
+    the optional-extras isolation invariant: ``import httpware`` must not pull
+    ``opentelemetry`` into ``sys.modules`` when the extra is absent.
+    """
+    logger.log(level, message, extra=attributes)
+    if import_checker.is_otel_installed:
+        from opentelemetry import trace  # noqa: PLC0415 — lazy by design (optional-extras isolation)
+
+        trace.get_current_span().add_event(event_name, attributes=attributes)

{httpware-0.4.0 → httpware-0.6.0}/src/httpware/client.py

@@ -1,7 +1,8 @@
 """AsyncClient — the thin httpx2 wrapper."""
 
+import contextlib
 import typing
-from collections.abc import Sequence
+from collections.abc import AsyncIterator, Sequence
 from http import HTTPStatus
 
 import httpx2
@@ -44,6 +45,48 @@ def _default_pydantic_decoder() -> ResponseDecoder:
     return PydanticDecoder()
 
 
+@contextlib.asynccontextmanager
+async def _httpx2_exception_mapper() -> AsyncIterator[None]:
+    """Map httpx2 exceptions to httpware exceptions. Shared by AsyncClient._terminal and stream()."""
+    try:
+        yield
+    except httpx2.TimeoutException as exc:
+        raise TimeoutError(str(exc)) from exc
+    except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
+        raise TransportError(str(exc)) from exc
+    except httpx2.NetworkError as exc:
+        raise NetworkError(str(exc)) from exc
+    except httpx2.HTTPError as exc:
+        raise TransportError(str(exc)) from exc
+
+
+def _raise_on_status_error(response: httpx2.Response) -> None:
+    """Raise the appropriate StatusError subclass for a 4xx/5xx response. No-op for 2xx/3xx."""
+    status = response.status_code
+    if HTTPStatus.BAD_REQUEST <= status < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
+        exc_class = STATUS_TO_EXCEPTION.get(
+            status,
+            ClientStatusError if status < HTTPStatus.INTERNAL_SERVER_ERROR else ServerStatusError,
+        )
+        raise exc_class(response)
+
+
+STREAMING_BODY_MARKER = "httpware.streaming_body"
+"""Key set on ``httpx2.Request.extensions`` by ``_request_with_body`` when content/data/files is an async-iterable.
+
+``Retry.__call__`` reads this marker to refuse retrying a streamed-body request
+(the consumed iterator cannot replay across attempts)."""
+
+
+def _is_streaming_body(value: typing.Any) -> bool:
+    """Return True if value is an async-iterable that cannot be safely replayed for retry."""
+    if value is None:
+        return False
+    if isinstance(value, (bytes, bytearray, memoryview, str, dict)):
+        return False
+    return hasattr(value, "__aiter__")
+
+
 class AsyncClient:
     """Async HTTP client: thin wrapper around httpx2 with typed decoding and middleware."""
 
@@ -106,26 +149,13 @@ class AsyncClient:
 
     async def _terminal(self, request: httpx2.Request) -> httpx2.Response:
         try:
-            response = await self._httpx2_client.send(request)
-        except httpx2.TimeoutException as exc:
-            raise TimeoutError(str(exc)) from exc
-        except (httpx2.InvalidURL, httpx2.CookieConflict) as exc:
-            raise TransportError(str(exc)) from exc
-        except httpx2.NetworkError as exc:
-            raise NetworkError(str(exc)) from exc
-        except httpx2.HTTPError as exc:
-            raise TransportError(str(exc)) from exc
+            async with _httpx2_exception_mapper():
+                response = await self._httpx2_client.send(request)
         except RuntimeError as exc:
             if "closed" in str(exc):
                 raise TransportError(str(exc)) from exc
             raise
-        status = response.status_code
-        if HTTPStatus.BAD_REQUEST <= status < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
-            exc_class = STATUS_TO_EXCEPTION.get(
-                status,
-                ClientStatusError if status < HTTPStatus.INTERNAL_SERVER_ERROR else ServerStatusError,
-            )
-            raise exc_class(response)
+        _raise_on_status_error(response)
         return response
 
     @typing.overload
@@ -150,7 +180,7 @@ class AsyncClient:
         """Delegate request construction to the wrapped httpx2.AsyncClient."""
         return self._httpx2_client.build_request(method, url, **kwargs)
 
-    async def _request_with_body(  # noqa: PLR0913 — mirrors httpx2 per-method signatures
+    async def _request_with_body(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
         self,
         method: str,
         url: str,
@@ -186,6 +216,8 @@ class AsyncClient:
         if files is not None:
             kwargs["files"] = files
         request = self._httpx2_client.build_request(method, url, **kwargs)
+        if _is_streaming_body(content) or _is_streaming_body(data) or _is_streaming_body(files):
+            request.extensions[STREAMING_BODY_MARKER] = True
         return await self.send(request, response_model=response_model)
 
     @typing.overload
@@ -663,6 +695,66 @@ class AsyncClient:
             response_model=response_model,
         )
 
+    @contextlib.asynccontextmanager
+    async def stream(  # noqa: PLR0913, C901 — mirrors httpx2 per-method signatures; kwargs-forwarding complexity is structural
+        self,
+        method: str,
+        url: str,
+        *,
+        params: typing.Any | None = None,
+        headers: typing.Any | None = None,
+        cookies: typing.Any | None = None,
+        timeout: typing.Any = httpx2.USE_CLIENT_DEFAULT,
+        extensions: typing.Any | None = None,
+        json: typing.Any | None = None,
+        content: typing.Any | None = None,
+        data: typing.Any | None = None,
+        files: typing.Any | None = None,
+    ) -> AsyncIterator[httpx2.Response]:
+        """Stream an HTTP response. Bypasses the middleware chain.
+
+        Yields an httpx2.Response; consume the body via response.aiter_bytes(),
+        response.aiter_text(), response.aiter_lines(), or response.aiter_raw().
+        The body is NOT pre-read for 2xx/3xx (streaming preserved); the response
+        is closed when the context exits.
+
+        Bypasses the middleware chain (no Retry, no Bulkhead, no user-installed
+        middleware) for v1 — see planning/specs/2026-06-05-streaming-design.md.
+
+        Auto-raises StatusError subclasses on 4xx/5xx (NotFoundError,
+        ServiceUnavailableError, etc.) — consistent with client.get()/post()/etc.
+        On error the response body is pre-read so exc.response.content is
+        accessible. You lose the streaming property on errors; rare in practice.
+
+        Maps httpx2 exceptions raised during the request OR body consumption to
+        httpware exceptions via _httpx2_exception_mapper.
+        """
+        kwargs: dict[str, typing.Any] = {}
+        if params is not None:
+            kwargs["params"] = params
+        if headers is not None:
+            kwargs["headers"] = headers
+        if cookies is not None:
+            kwargs["cookies"] = cookies
+        if timeout is not httpx2.USE_CLIENT_DEFAULT:
+            kwargs["timeout"] = timeout
+        if extensions is not None:
+            kwargs["extensions"] = extensions
+        if json is not None:
+            kwargs["json"] = json
+        if content is not None:
+            kwargs["content"] = content
+        if data is not None:
+            kwargs["data"] = data
+        if files is not None:
+            kwargs["files"] = files
+
+        async with _httpx2_exception_mapper(), self._httpx2_client.stream(method, url, **kwargs) as response:
+            if HTTPStatus.BAD_REQUEST <= response.status_code < 600:  # noqa: PLR2004 — 600 is the synthetic upper bound for 5xx
+                await response.aread()  # pre-read body so exc.response.content works
+                _raise_on_status_error(response)
+            yield response
+
     async def __aenter__(self) -> typing.Self:
         """Enter the async context manager; return self."""
         return self

{httpware-0.4.0 → httpware-0.6.0}/src/httpware/middleware/resilience/bulkhead.py

@@ -12,9 +12,11 @@ AsyncClient(middleware=[shared]) calls to enforce a joint cap across clients.
 """
 
 import asyncio
+import logging
 
 import httpx2
 
+from httpware._internal.observability import _emit_event
 from httpware.errors import BulkheadFullError
 from httpware.middleware import Next
 
@@ -22,6 +24,8 @@ from httpware.middleware import Next
 _MAX_CONCURRENT_INVALID = "max_concurrent must be >= 1"
 _ACQUIRE_TIMEOUT_INVALID = "acquire_timeout must be >= 0"
 
+_LOGGER = logging.getLogger("httpware.bulkhead")
+
 
 class Bulkhead:
     """Concurrency limiter middleware backed by ``asyncio.Semaphore``.
@@ -64,6 +68,18 @@ class Bulkhead:
                 async with asyncio.timeout(self._acquire_timeout):
                     await self._sem.acquire()
         except TimeoutError as exc:
+            _emit_event(
+                _LOGGER,
+                "bulkhead.rejected",
+                level=logging.WARNING,
+                message="bulkhead rejected request — acquire_timeout exceeded",
+                attributes={
+                    "max_concurrent": self._max_concurrent,
+                    "acquire_timeout": self._acquire_timeout,
+                    "method": request.method,
+                    "url": str(request.url),
+                },
+            )
             raise BulkheadFullError(
                 max_concurrent=self._max_concurrent,
                 acquire_timeout=self._acquire_timeout,

{httpware-0.4.0 → httpware-0.6.0}/src/httpware/middleware/resilience/retry.py

@@ -11,11 +11,14 @@ import asyncio
 import builtins
 import datetime
 import email.utils
+import logging
 from collections.abc import Awaitable, Callable
 from http import HTTPStatus
 
 import httpx2
 
+from httpware._internal.observability import _emit_event
+from httpware.client import STREAMING_BODY_MARKER
 from httpware.errors import NetworkError, RetryBudgetExhaustedError, StatusError, TimeoutError  # noqa: A004
 from httpware.middleware import Next
 from httpware.middleware.resilience._backoff import full_jitter_delay
@@ -43,6 +46,9 @@ DEFAULT_IDEMPOTENT_METHODS = frozenset(
 )
 
 _MAX_ATTEMPTS_INVALID = "max_attempts must be >= 1"
+_STREAMING_BODY_REFUSAL_NOTE = "httpware: not retrying — request body is a stream that cannot replay across attempts"
+
+_LOGGER = logging.getLogger("httpware.retry")
 
 
 def _parse_retry_after(value: str) -> float | None:
@@ -90,7 +96,7 @@ class Retry:
         self.budget = budget if budget is not None else RetryBudget()
         self._sleep = _sleep
 
-    async def __call__(self, request: httpx2.Request, next: Next) -> httpx2.Response:  # noqa: A002, C901, PLR0912 — complexity budget: 3 error clauses + idempotency gate + budget gate + Retry-After branch + backoff
+    async def __call__(self, request: httpx2.Request, next: Next) -> httpx2.Response:  # noqa: A002, C901, PLR0912, PLR0915 — complexity budget: 3 error clauses + idempotency gate + streaming-body refusal + budget gate + Retry-After branch + backoff
         """Process a request through the retry loop. See module docstring."""
         method_eligible = request.method.upper() in self.retry_methods
         last_exc: BaseException | None = None
@@ -106,12 +112,17 @@ class Retry:
                 else:
                     return await next(request)
             except StatusError as exc:
-                if not method_eligible or exc.response.status_code not in self.retry_status_codes:
+                retryable_status = exc.response.status_code in self.retry_status_codes
+                if not method_eligible or not retryable_status:
+                    if retryable_status and request.extensions.get(STREAMING_BODY_MARKER):
+                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise
                 last_exc = exc
                 last_response = exc.response
             except (NetworkError, TimeoutError) as exc:
                 if not method_eligible:
+                    if request.extensions.get(STREAMING_BODY_MARKER):
+                        exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise
                 last_exc = exc
                 last_response = None
@@ -119,19 +130,64 @@ class Retry:
                 wrapped = TimeoutError("attempt timed out")
                 wrapped.__cause__ = exc  # set now; the retry path (last_exc = wrapped) has no `from` clause
                 if not method_eligible:
+                    if request.extensions.get(STREAMING_BODY_MARKER):
+                        wrapped.add_note(_STREAMING_BODY_REFUSAL_NOTE)
                     raise wrapped from exc
                 last_exc = wrapped
                 last_response = None
 
             # ---- retryable failure path
+            if request.extensions.get(STREAMING_BODY_MARKER):
+                if last_exc is None:  # pragma: no cover — invariant from except branch
+                    msg = "Retry: streaming-body refusal reached with no last_exc"
+                    raise AssertionError(msg)
+                last_exc.add_note(_STREAMING_BODY_REFUSAL_NOTE)
+                _emit_event(
+                    _LOGGER,
+                    "retry.streaming_refused",
+                    level=logging.WARNING,
+                    message="retry refused — request body is a stream that cannot replay",
+                    attributes={
+                        "method": request.method,
+                        "url": str(request.url),
+                        "last_exception_type": type(last_exc).__qualname__,
+                    },
+                )
+                raise last_exc
+
             if is_last:
                 if last_exc is None:  # pragma: no cover — structural invariant from except branch
                     msg = "Retry: last_exc unset on final attempt — unreachable"
                     raise AssertionError(msg)
                 last_exc.add_note(f"httpware: gave up after {attempt + 1} attempts")
+                _emit_event(
+                    _LOGGER,
+                    "retry.giving_up",
+                    level=logging.WARNING,
+                    message=f"retry gave up after {attempt + 1} attempts",
+                    attributes={
+                        "attempts": attempt + 1,
+                        "method": request.method,
+                        "url": str(request.url),
+                        "last_status": last_response.status_code if last_response is not None else None,
+                        "last_exception_type": type(last_exc).__qualname__,
+                    },
+                )
                 raise last_exc
 
             if not self.budget.try_withdraw():
+                _emit_event(
+                    _LOGGER,
+                    "retry.budget_refused",
+                    level=logging.WARNING,
+                    message=f"retry budget refused after {attempt + 1} attempts",
+                    attributes={
+                        "attempts": attempt + 1,
+                        "method": request.method,
+                        "url": str(request.url),
+                        "last_status": last_response.status_code if last_response is not None else None,
+                    },
+                )
                 raise RetryBudgetExhaustedError(
                     last_response=last_response,
                     last_exception=last_exc,