coderouter-cli 2.13.0__py3-none-any.whl → 2.15.0__py3-none-any.whl

coderouter/routing/fallback.py

@@ -46,6 +46,7 @@ from coderouter.adapters.base import (
     ChatResponse,
     ProviderCallOverrides,
     StreamChunk,
+    StreamTruncatedError,
 )
 from coderouter.adapters.registry import build_adapter
 from coderouter.config.schemas import CodeRouterConfig, ProviderConfig
@@ -79,6 +80,7 @@ from coderouter.logging import (
     log_chain_paid_gate_blocked,
     log_demote_unhealthy_provider,
     log_empty_response_detected,
+    log_fallback_occurred,
     log_memory_pressure_detected,
     log_skip_budget_exceeded,
     log_skip_memory_pressure,
@@ -100,6 +102,23 @@ from coderouter.routing.capability import (
     strip_cache_control,
     strip_thinking,
 )
+from coderouter.routing.fallback_trace import (
+    REASON_BACKEND_UNHEALTHY,
+    REASON_BUDGET_EXCEEDED,
+    REASON_EMPTY_RESPONSE,
+    REASON_EMPTY_STREAM,
+    REASON_MEMORY_PRESSURE,
+    REASON_PAID_GATE,
+    REASON_SELF_HEALING_EXCLUDED,
+    REASON_STREAM_TRUNCATED,
+    REASON_UNKNOWN_PROVIDER,
+    FallbackTrace,
+    begin_fallback_trace,
+    classify_adapter_error,
+    current_fallback_trace,
+    describe_adapter_error,
+    ensure_fallback_trace,
+)
 from coderouter.translation import (
     AnthropicRequest,
     AnthropicResponse,
@@ -1053,6 +1072,36 @@ def _stream_event_is_real_content(event: AnthropicStreamEvent) -> bool:
     return False
 
 
+def _log_fallback_trace(trace: FallbackTrace | None, *, profile: str | None) -> None:
+    """v2.15.0: emit one ``fallback-occurred`` line per recorded hop.
+
+    Called at every terminal point of a dispatch (successful return,
+    chain-exhausted raise, empty-chain flush). Deferring the emission to
+    the end is what lets each line carry a resolved ``to_provider`` — at
+    the moment a provider fails, the engine does not yet know who (if
+    anyone) will take over.
+
+    The ``logged`` latch makes the call idempotent, so a path with several
+    ``return`` statements cannot double-log. A request whose first
+    provider served produces no lines at all.
+    """
+    if trace is None or trace.logged or not trace.hops:
+        return
+    trace.logged = True
+    for index, hop in enumerate(trace.hops):
+        log_fallback_occurred(
+            logger,
+            from_provider=hop.from_provider,
+            to_provider=hop.to_provider,
+            reason=hop.reason,
+            detail=hop.detail,
+            profile=trace.profile or profile,
+            stream=hop.stream,
+            pre_attempt=hop.pre_attempt,
+            hop_index=index,
+        )
+
+
 class FallbackEngine:
     """Sequential fallback router — the core of CodeRouter.
 
@@ -1989,12 +2038,21 @@ class FallbackEngine:
         Invariant across every adapter call on one chain (profiles are
         immutable per request), so callers resolve this once at the top of
         each engine method and pass to every adapter invocation.
+
+        v2.15.0: ``stream_truncation_action`` rides along. It is not a
+        provider-level knob, but the adapter's SSE parse loop is the only
+        place that can see a missing terminator, and this object is the
+        channel that already reaches it. ``getattr`` with an ``off`` default
+        keeps ``model_construct``-built / stub profiles working.
         """
         chosen = profile_name or self.config.default_profile
         profile = self.config.profile_by_name(chosen)
         return ProviderCallOverrides(
             timeout_s=profile.timeout_s,
             append_system_prompt=profile.append_system_prompt,
+            stream_truncation_action=getattr(
+                profile, "stream_truncation_action", "off"
+            ),
         )
 
     def _resolve_shim_actions(self, profile_name: str | None) -> tuple[str, str]:
@@ -2062,6 +2120,13 @@ class FallbackEngine:
         """
         chosen = profile_name or self.config.default_profile
         chain = self.config.profile_by_name(chosen)
+        # v2.15.0: every gate below that removes a provider also records a
+        # pre-attempt hop on the request-scoped fallback trace, so the
+        # ingress can answer "why did my request not go to `local`?" with
+        # `budget-exceeded` instead of silence. ``ensure_`` (not ``begin_``)
+        # because this method also runs from the ingress's
+        # ``apply_context_budget`` pre-pass, before dispatch starts a trace.
+        trace = ensure_fallback_trace(profile=chosen)
 
         # Pass 1: paid gate. Same shape as v0.6-C; produces the
         # post-paid candidate list and tracks the names that were
@@ -2076,6 +2141,7 @@ class FallbackEngine:
                     "skip-unknown-provider",
                     extra={"profile": chosen, "provider": prov_name},
                 )
+                trace.record_skip(prov_name, REASON_UNKNOWN_PROVIDER)
                 continue
             if provider_cfg.paid and not self.config.allow_paid:
                 logger.info(
@@ -2083,6 +2149,7 @@ class FallbackEngine:
                     extra={"profile": chosen, "provider": prov_name},
                 )
                 blocked_by_paid.append(prov_name)
+                trace.record_skip(prov_name, REASON_PAID_GATE)
                 continue
             post_paid.append((prov_name, self._adapters[prov_name], provider_cfg))
 
@@ -2107,6 +2174,11 @@ class FallbackEngine:
                     month=self._budget.current_month(),
                 )
                 blocked_by_budget.append(prov_name)
+                trace.record_skip(
+                    prov_name,
+                    REASON_BUDGET_EXCEEDED,
+                    detail=f"monthly_budget_usd={budget_usd}",
+                )
                 continue
             post_budget.append((prov_name, adapter))
 
@@ -2134,6 +2206,11 @@ class FallbackEngine:
                     seconds_until_eligible=seconds,
                 )
                 blocked_by_pressure.append(prov_name)
+                trace.record_skip(
+                    prov_name,
+                    REASON_MEMORY_PRESSURE,
+                    detail=f"eligible_in_s={seconds}",
+                )
                 continue
             adapters.append(adapter)
 
@@ -2209,6 +2286,11 @@ class FallbackEngine:
         if chain.backend_health_action == "exclude":
             excluded = self.self_healing.excluded_providers()
             if excluded:
+                for adapter in adapters:
+                    if adapter.name in excluded:
+                        trace.record_skip(
+                            adapter.name, REASON_SELF_HEALING_EXCLUDED
+                        )
                 adapters = [a for a in adapters if a.name not in excluded]
 
         # Pass 4c: v2.x ``skip`` action — self-contained half-open circuit
@@ -2223,6 +2305,7 @@ class FallbackEngine:
         # failing with NoProvidersAvailableError before trying anything.
         if chain.backend_health_action == "skip":
             kept: list[BaseAdapter] = []
+            skipped_unhealthy: list[str] = []
             for adapter in adapters:
                 if self._backend_health.should_skip(
                     adapter.name,
@@ -2233,10 +2316,17 @@ class FallbackEngine:
                         provider=adapter.name,
                         profile=chosen,
                     )
+                    skipped_unhealthy.append(adapter.name)
                 else:
                     kept.append(adapter)
             if kept:
                 adapters = kept
+                # v2.15.0: only record the skips that actually took effect.
+                # In the last-resort branch below nobody is removed, so
+                # recording there would invent a fallback that never
+                # happened.
+                for name in skipped_unhealthy:
+                    trace.record_skip(name, REASON_BACKEND_UNHEALTHY)
             elif adapters:
                 # Everyone was skipped — last-resort: try the unfiltered
                 # chain rather than 502 without attempting a single provider.
@@ -2385,10 +2475,17 @@ class FallbackEngine:
         the full per-provider error list so the ingress layer can
         surface a single 502.
         """
+        # v2.15.0: open the trace *before* chain resolution so the gate
+        # skips inside ``_resolve_chain`` land on this request's trace and
+        # not on a leftover from an earlier call in the same context.
+        trace = begin_fallback_trace(
+            profile=request.profile or self.config.default_profile
+        )
         adapters = self._resolve_chain(request.profile)
         overrides = self._resolve_profile_overrides(request.profile)
         errors: list[AdapterError] = []
         for adapter in adapters:
+            trace.record_attempt(adapter.name)
             logger.info(
                 "try-provider",
                 extra={"provider": adapter.name, "stream": False},
@@ -2416,6 +2513,7 @@ class FallbackEngine:
                 self._observe_provider_success(
                     adapter.name, profile=request.profile
                 )
+                _log_fallback_trace(trace, profile=request.profile)
                 return response
             except AdapterError as exc:
                 # M2: record the failed attempt. Auth failures carry no
@@ -2444,10 +2542,17 @@ class FallbackEngine:
                     adapter.name, exc, profile=request.profile
                 )
                 errors.append(exc)
+                trace.record_failure(
+                    adapter.name,
+                    classify_adapter_error(exc),
+                    detail=describe_adapter_error(exc),
+                    stream=False,
+                )
                 if not exc.retryable:
                     break
         profile = request.profile or self.config.default_profile
         _warn_if_uniform_auth_failure(errors, profile=profile)
+        _log_fallback_trace(trace, profile=profile)
         raise NoProvidersAvailableError(profile=profile, errors=errors)
 
     async def stream(self, request: ChatRequest) -> AsyncIterator[StreamChunk]:
@@ -2473,10 +2578,15 @@ class FallbackEngine:
         fall back mid-stream (the client has already received partial content).
         We only fall through if the *initial* response is an error.
         """
+        # v2.15.0: mirror of ``_generate_impl`` — see the comment there.
+        trace = begin_fallback_trace(
+            profile=request.profile or self.config.default_profile
+        )
         adapters: list[BaseAdapter] = self._resolve_chain(request.profile)
         overrides = self._resolve_profile_overrides(request.profile)
         errors: list[AdapterError] = []
         for adapter in adapters:
+            trace.record_attempt(adapter.name)
             logger.info(
                 "try-provider",
                 extra={"provider": adapter.name, "stream": True},
@@ -2498,6 +2608,9 @@ class FallbackEngine:
                     success=False,
                 )
                 errors.append(AdapterError("empty stream", provider=adapter.name, retryable=True))
+                trace.record_failure(
+                    adapter.name, REASON_EMPTY_STREAM, stream=True
+                )
                 continue
             except AdapterError as exc:
                 # M2: record the pre-first-event failure.
@@ -2524,6 +2637,12 @@ class FallbackEngine:
                     adapter.name, exc, profile=request.profile
                 )
                 errors.append(exc)
+                trace.record_failure(
+                    adapter.name,
+                    classify_adapter_error(exc),
+                    detail=describe_adapter_error(exc),
+                    stream=True,
+                )
                 if not exc.retryable:
                     break
                 continue
@@ -2546,6 +2665,7 @@ class FallbackEngine:
             self._observe_provider_success(
                 adapter.name, profile=request.profile
             )
+            _log_fallback_trace(trace, profile=request.profile)
             yield first
             # Mid-stream fallback guard: once the first byte is out the door,
             # any subsequent adapter exception is terminal — we cannot fall
@@ -2583,6 +2703,7 @@ class FallbackEngine:
 
         profile = request.profile or self.config.default_profile
         _warn_if_uniform_auth_failure(errors, profile=profile)
+        _log_fallback_trace(trace, profile=profile)
         raise NoProvidersAvailableError(profile=profile, errors=errors)
 
     # ==================================================================
@@ -2626,6 +2747,23 @@ class FallbackEngine:
         """
         chain = self._resolve_anthropic_chain(request)
         first_provider_config = chain[0][0].config if chain else None
+        # v2.15.0: ``_resolve_chain`` (called above, underneath
+        # ``_resolve_anthropic_chain``) recorded a pre-attempt hop for every
+        # provider a gate removed — paid / budget / memory-pressure /
+        # backend-health — but each of those hops is still missing its
+        # ``to_provider``. Here, and only here, the successor is already
+        # known: ``chain`` is post-reorder (adaptive, drift demotion,
+        # thinking-capability bucketing), so its head is the provider the
+        # engine will actually try first. Resolving now is what lets the
+        # streaming ingress ship a complete ``X-CodeRouter-Fallback-To``
+        # header, since SSE headers commit before the generator starts.
+        # Runtime attempt failures are still resolved later by
+        # ``record_attempt``; ``resolve_pending`` only fills hops holding
+        # ``None``, so the two cannot contradict each other.
+        if chain:
+            budget_trace = current_fallback_trace()
+            if budget_trace is not None:
+                budget_trace.resolve_pending(chain[0][0].name)
         trimmed_request, status = _apply_context_budget_guard(
             request, config=self.config, first_provider_config=first_provider_config,
         )
@@ -2810,6 +2948,15 @@ class FallbackEngine:
         # ``skip_prepared_dispatch`` (swap) forces a fresh resolution —
         # see ``generate_anthropic``'s docstring.
         prepared = None if skip_prepared_dispatch else self._take_prepared_dispatch(request)
+        # v2.15.0: open the request-scoped fallback trace. ``keep_existing``
+        # is True exactly when the M11 prepared dispatch was consumed —
+        # proof that the ingress already resolved the chain for *this*
+        # request, so the pre-attempt hops it recorded (budget / health /
+        # paid gate) must be carried forward rather than dropped.
+        trace = begin_fallback_trace(
+            keep_existing=prepared is not None,
+            profile=request.profile or self.config.default_profile,
+        )
         if prepared is not None:
             chain = prepared.chain
             request = prepared.request
@@ -2886,6 +3033,10 @@ class FallbackEngine:
                 action=cache_control_action,
                 request_had_cache_control=request_had_cache_control,
             )
+            # v2.15.0: recording the attempt resolves every pending hop's
+            # ``to_provider`` — including consecutive chain-resolve skips,
+            # which all point at whoever actually ran.
+            trace.record_attempt(adapter.name)
             logger.info(
                 "try-provider",
                 extra={
@@ -2958,6 +3109,16 @@ class FallbackEngine:
                     stream=False,
                 )
                 errors.append(exc)
+                # v2.15.0: capture the departure reason (timeout / 5xx /
+                # auth / ...). Non-retryable errors are recorded too: the
+                # hop simply never gets a ``to_provider``, which is exactly
+                # the "we left and had nowhere to go" narrative.
+                trace.record_failure(
+                    adapter.name,
+                    classify_adapter_error(exc),
+                    detail=describe_adapter_error(exc),
+                    stream=False,
+                )
                 if not exc.retryable:
                     break
                 continue
@@ -3019,6 +3180,9 @@ class FallbackEngine:
                     log_empty_response_detected(
                         logger, adapter.name, action="fallback", stream=False
                     )
+                    trace.record_failure(
+                        adapter.name, REASON_EMPTY_RESPONSE, stream=False
+                    )
                     continue
                 # ``warn``: log only; fall through and return the empty resp.
                 log_empty_response_detected(
@@ -3062,6 +3226,7 @@ class FallbackEngine:
                 latency_ms=(time.monotonic() - attempt_started) * 1000.0,
                 stream=False,
             )
+            _log_fallback_trace(trace, profile=request.profile)
             return resp
 
         # ⑧ (empty-response): the chain is exhausted. Under ``fallback``,
@@ -3076,10 +3241,12 @@ class FallbackEngine:
                 stream=False,
                 chain_exhausted=True,
             )
+            _log_fallback_trace(trace, profile=request.profile)
             return last_empty_resp
 
         profile = request.profile or self.config.default_profile
         _warn_if_uniform_auth_failure(errors, profile=profile)
+        _log_fallback_trace(trace, profile=profile)
         raise NoProvidersAvailableError(profile=profile, errors=errors)
 
     async def stream_anthropic(
@@ -3127,6 +3294,12 @@ class FallbackEngine:
         # non-streaming path — avoids a redundant resolution + estimate.
         # ``skip_prepared_dispatch`` (swap) forces a fresh resolution.
         prepared = None if skip_prepared_dispatch else self._take_prepared_dispatch(request)
+        # v2.15.0: mirror of the non-streaming path — see the comment there
+        # for why ``keep_existing`` tracks the prepared dispatch.
+        trace = begin_fallback_trace(
+            keep_existing=prepared is not None,
+            profile=request.profile or self.config.default_profile,
+        )
         if prepared is not None:
             chain = prepared.chain
             request = prepared.request
@@ -3158,6 +3331,18 @@ class FallbackEngine:
         empty_response_action = self._resolve_empty_response_action(request.profile)
         empty_fallback = empty_response_action == "fallback"
         last_empty_stream_buffer: list[AnthropicStreamEvent] | None = None
+        # v2.15.0 (stream-truncation): does the buffer we are holding
+        # *terminate* the message? An empty stream's buffer does — it is a
+        # complete ``message_start`` … ``message_stop`` sequence, which is
+        # why flushing it on chain exhaustion gives the client a well-formed
+        # 200 blank. A truncated stream's buffer does NOT, by definition:
+        # the upstream went quiet with the message still open. Flushing that
+        # would hand the client an unterminated SSE stream and hang it, so
+        # the flush at the bottom is gated on this flag. Only
+        # ``stream_truncation_action: error`` can ever set it True (under
+        # ``off`` / ``warn`` no ``StreamTruncatedError`` is raised), which
+        # keeps the default byte-for-byte identical to v2.14.0.
+        last_empty_stream_truncated = False
 
         for adapter, will_degrade in chain:
             is_native = isinstance(adapter, AnthropicAdapter)
@@ -3191,6 +3376,8 @@ class FallbackEngine:
                 action=cache_control_action,
                 request_had_cache_control=request_had_cache_control,
             )
+            # v2.15.0: see the non-streaming sibling.
+            trace.record_attempt(adapter.name)
             logger.info(
                 "try-provider",
                 extra={
@@ -3253,6 +3440,9 @@ class FallbackEngine:
                     success=False,
                 )
                 errors.append(AdapterError("empty stream", provider=adapter.name, retryable=True))
+                trace.record_failure(
+                    adapter.name, REASON_EMPTY_STREAM, stream=True
+                )
                 continue
             except AdapterError as exc:
                 # M2: record the pre-first-event failure. Auth failures
@@ -3289,6 +3479,14 @@ class FallbackEngine:
                     stream=True,
                 )
                 errors.append(exc)
+                # v2.15.0: pre-first-event failure — no bytes reached the
+                # client, so this really is a fallback.
+                trace.record_failure(
+                    adapter.name,
+                    classify_adapter_error(exc),
+                    detail=describe_adapter_error(exc),
+                    stream=True,
+                )
                 if not exc.retryable:
                     break
                 continue
@@ -3362,10 +3560,62 @@ class FallbackEngine:
                     self._adaptive.record_attempt(
                         adapter.name, latency_ms=None, success=False
                     )
-                    log_empty_response_detected(
-                        logger, adapter.name, action="fallback", stream=True
+                    # v2.15.0 (self-healing): the guards learn about this
+                    # branch too. ``_observe_provider_success`` already fired
+                    # the moment the first event landed, so without the two
+                    # observations below a backend that opens a stream and
+                    # then goes quiet keeps a *clean* bill of health on L2 /
+                    # L4 / L5 — and adaptive routing would keep preferring it
+                    # for its fast first byte. That is the opposite of what
+                    # this feature is for. The calls mirror the mid-stream
+                    # sibling below verbatim; the only difference in this
+                    # branch is that no bytes reached the client, so we fall
+                    # back instead of raising ``MidStreamError``.
+                    #
+                    # This is deliberately NOT gated on
+                    # ``StreamTruncatedError``: an ``AdapterError`` raised
+                    # here means the provider genuinely failed, whatever the
+                    # label. The pre-v2.15.0 behavior made provider health
+                    # depend on ``empty_response_action`` — an unrelated
+                    # knob — because the identical failure under ``off`` /
+                    # ``warn`` goes down the mid-stream path and *is*
+                    # observed. A truly empty-but-clean stream is a
+                    # different case entirely: it exits the loop normally
+                    # (see below) and is still not treated as a failure.
+                    self._observe_provider_failure(
+                        adapter.name, exc, profile=request.profile
                     )
+                    self._observe_drift_signal(
+                        adapter.name,
+                        profile=request.profile,
+                        is_error=True,
+                        request_had_tools=bool(request.tools),
+                        stream=True,
+                    )
+                    errors.append(exc)
+                    # v2.15.0 (stream-truncation): same branch, different
+                    # label. A truncated stream is not an *empty* one — the
+                    # upstream produced events, it just never finished the
+                    # message — so the hop is recorded as ``stream-truncated``
+                    # and the empty-response log is skipped. The adapter has
+                    # already emitted ``stream-truncation-detected``.
+                    truncated = isinstance(exc, StreamTruncatedError)
+                    if truncated:
+                        trace.record_failure(
+                            adapter.name,
+                            REASON_STREAM_TRUNCATED,
+                            detail=describe_adapter_error(exc),
+                            stream=True,
+                        )
+                    else:
+                        log_empty_response_detected(
+                            logger, adapter.name, action="fallback", stream=True
+                        )
+                        trace.record_failure(
+                            adapter.name, REASON_EMPTY_STREAM, stream=True
+                        )
                     last_empty_stream_buffer = buffer
+                    last_empty_stream_truncated = truncated
                     continue
                 # M2: mid-stream failure — record an error-only
                 # observation (no latency; first-event success already
@@ -3407,7 +3657,13 @@ class FallbackEngine:
                 log_empty_response_detected(
                     logger, adapter.name, action="fallback", stream=True
                 )
+                trace.record_failure(
+                    adapter.name, REASON_EMPTY_STREAM, stream=True
+                )
                 last_empty_stream_buffer = buffer
+                # The stream ended *cleanly* — this buffer is a complete
+                # message_start … message_stop sequence and is safe to flush.
+                last_empty_stream_truncated = False
                 continue
             # v2.0-G (L4): drift detection observation (stream success).
             # P1-4: compute response fingerprint for goal_progress_stall.
@@ -3462,14 +3718,56 @@ class FallbackEngine:
                 latency_ms=None,  # streaming latency is end-of-stream-relative; left to plugin
                 stream=True,
             )
+            _log_fallback_trace(trace, profile=request.profile)
             return
 
         # ⑧ (empty-response): the chain is exhausted under ``fallback`` and
         # every provider produced an empty stream. Flush the last buffered
         # (empty) preamble so the client gets a well-formed, terminating SSE
         # sequence (message_start … message_stop) instead of an error — a
-        # 200 blank is a legitimate answer. errors is empty in that case.
-        if last_empty_stream_buffer is not None:
+        # 200 blank is a legitimate answer.
+        #
+        # v2.15.0 (stream-truncation): ``last_empty_stream_truncated`` gates
+        # this. The buffer of a *truncated* stream stops mid-message — it has
+        # no ``message_stop`` — so flushing it would emit an unterminated SSE
+        # stream, no exception, no error frame, and a client that waits
+        # forever. It would also fire ``empty-response-detected`` for a
+        # stream that was not empty at all, inflating
+        # ``empty_responses_total``. When the buffer we are holding came from
+        # a truncation we fall through to ``NoProvidersAvailableError``
+        # instead: the ingress turns that into an ``event: error``
+        # (``overloaded_error``) frame, which terminates the stream and tells
+        # the operator the truth. An operator who set
+        # ``stream_truncation_action: error`` asked not to have truncation
+        # swallowed; silently synthesizing an ``end_turn`` over a half-written
+        # answer would be exactly that. Under the default ``off`` no
+        # ``StreamTruncatedError`` exists, the flag is never set, and this
+        # path is byte-identical to v2.14.0.
+        #
+        # v2.15.0 post-review fix: ``last_empty_stream_truncated`` only ever
+        # becomes True for a ``StreamTruncatedError`` — it says nothing about
+        # a transport break (``httpx.RemoteProtocolError``) or a read timeout
+        # further down the same chain, which leave an equally unterminated
+        # buffer (no ``message_stop``) but arrive as a plain ``AdapterError``.
+        # Under ``stream_truncation_action: error`` those must not be
+        # flushed either, or the client hangs on an unterminated SSE stream
+        # exactly like the case above — the operator asked not to have
+        # truncation swallowed, and a TCP-level break mid-message is a
+        # truncation. ``_buffer_unterminated`` is gated on ``error`` so
+        # ``off`` / ``warn`` never reach the buffer inspection below and stay
+        # byte-identical to v2.14.0 — under those actions a buffer with no
+        # ``message_stop`` can legitimately be a clean-but-empty stream
+        # (preamble only, no content, no terminator emitted by the
+        # translator) that v2.14.0 flushes as a 200 blank.
+        _buffer_unterminated = (
+            overrides.stream_truncation_action == "error"
+            and not any(
+                ev.type == "message_stop" for ev in (last_empty_stream_buffer or [])
+            )
+        )
+        if last_empty_stream_buffer is not None and not (
+            last_empty_stream_truncated or _buffer_unterminated
+        ):
             log_empty_response_detected(
                 logger,
                 "unknown",
@@ -3477,10 +3775,12 @@ class FallbackEngine:
                 stream=True,
                 chain_exhausted=True,
             )
+            _log_fallback_trace(trace, profile=request.profile)
             for buffered_ev in last_empty_stream_buffer:
                 yield buffered_ev
             return
 
         profile = request.profile or self.config.default_profile
         _warn_if_uniform_auth_failure(errors, profile=profile)
+        _log_fallback_trace(trace, profile=profile)
         raise NoProvidersAvailableError(profile=profile, errors=errors)