Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

fix(tracing): Recorder/Meter subscribe to every provider in FallbackBoundModel chain

xf gong5c6c6aba4e77
diff --git a/cubepi/providers/fallback.py b/cubepi/providers/fallback.py
index 6ad6232..bdefa10 100644
--- a/cubepi/providers/fallback.py
+++ b/cubepi/providers/fallback.py
@@ -53,11 +53,11 @@ class FallbackBoundModel:
provider and spec proxy chain[0] so tracing/billing code that reads
agent._model.provider / agent._model.spec continues to work unchanged.
- Known limitation: Tracer.attach() and Meter.attach() subscribe only to
- chain[0].provider. Successful fallback calls (chain[1..]) are invisible to
- provider-level observability (chat spans, token/cost metrics). Tracked as a
- follow-up: update recorder.py and meter.py to iterate chain and subscribe
- to every unique BaseProvider.
+ Tracer / Meter coverage: Recorder.attach() and Meter.attach() detect
+ FallbackBoundModel and subscribe to every unique BaseProvider in the
+ chain (via chain_providers() below), so post-failover chat spans and
+ provider metrics land in the trace / metric stream like primary-leg
+ calls do.
"""
chain: tuple[BoundModel, ...]
@@ -230,3 +230,34 @@ class FallbackBoundModel:
raise ProviderUnavailable(
f"all providers exhausted; last error: {last_error!r}"
)
+
+
+def chain_providers(model: object) -> list[Any]:
+ """Return the unique BaseProvider instances backing a bound model.
+
+ For :class:`FallbackBoundModel`, iterates ``chain`` and dedupes providers
+ by identity. For a plain :class:`BoundModel` returns ``[model.provider]``.
+ For anything else (or ``None``) returns ``[]``.
+
+ Used by :meth:`cubepi.tracing.recorder.Recorder.attach` and
+ :meth:`cubepi.tracing.meter.Meter.attach` to subscribe to every leg of a
+ fallback chain so post-failover provider events land in the trace /
+ metric stream.
+ """
+ from cubepi.providers.base import BaseProvider
+
+ if model is None:
+ return []
+ if isinstance(model, FallbackBoundModel):
+ seen: set[int] = set()
+ out: list[Any] = []
+ for bm in model.chain:
+ p = bm.provider
+ if isinstance(p, BaseProvider) and id(p) not in seen:
+ seen.add(id(p))
+ out.append(p)
+ return out
+ provider = getattr(model, "provider", None)
+ if isinstance(provider, BaseProvider):
+ return [provider]
+ return []
diff --git a/cubepi/tracing/meter.py b/cubepi/tracing/meter.py
index cadf791..83c0c84 100644
--- a/cubepi/tracing/meter.py
+++ b/cubepi/tracing/meter.py
@@ -153,6 +153,7 @@ class Meter:
before its response landed).
"""
from cubepi.providers.base import BaseProvider
+ from cubepi.providers.fallback import chain_providers
state = _MeterState()
@@ -175,16 +176,21 @@ class Meter:
unsub_agent = agent.subscribe(_on_agent_event)
agent_model = getattr(agent, "_model", None)
- provider = (
- agent_model.provider
- if agent_model is not None
- else getattr(agent, "provider", None)
- )
+ # When the bound model is a FallbackBoundModel, subscribe to every
+ # unique provider in the chain so post-failover token usage / cost
+ # / cache-hit metrics are emitted for chain[1..] calls the same way
+ # as chain[0]. Non-fallback models yield a single-entry list.
+ agent_providers: list[Any] = chain_providers(agent_model)
+ if not agent_providers:
+ legacy = getattr(agent, "provider", None)
+ if legacy is not None:
+ agent_providers = [legacy]
detachers: list[Callable[[], None]] = []
- if isinstance(provider, BaseProvider):
- detachers.append(provider.subscribe_request(_on_request))
- detachers.append(provider.subscribe_chunk(_on_chunk))
- detachers.append(provider.subscribe_response(_on_response))
+ for provider in agent_providers:
+ if isinstance(provider, BaseProvider):
+ detachers.append(provider.subscribe_request(_on_request))
+ detachers.append(provider.subscribe_chunk(_on_chunk))
+ detachers.append(provider.subscribe_response(_on_response))
def detach() -> None:
unsub_agent()
diff --git a/cubepi/tracing/recorder.py b/cubepi/tracing/recorder.py
index 9bc79f3..9cdcab7 100644
--- a/cubepi/tracing/recorder.py
+++ b/cubepi/tracing/recorder.py
@@ -233,6 +233,7 @@ class Recorder:
def attach(self, agent: "Agent") -> Callable[[], None]:
from cubepi.providers.base import BaseProvider
+ from cubepi.providers.fallback import chain_providers
self._agent = agent
unsub_agent = agent.subscribe(self._on_agent_event)
@@ -240,11 +241,19 @@ class Recorder:
# reached via ``_model.provider``. Fall back to a public ``provider``
# alias should one be added later.
agent_model = getattr(agent, "_model", None)
- provider = (
- agent_model.provider
- if agent_model is not None
- else getattr(agent, "provider", None)
- )
+ # When the bound model is a FallbackBoundModel, subscribe to every
+ # unique provider in the chain so post-failover provider events
+ # (chat spans, token usage, errors) land in the trace tree like
+ # primary-leg events do. Non-fallback models yield a single-entry
+ # list with the only provider.
+ agent_providers: list[Any] = chain_providers(agent_model)
+ if not agent_providers:
+ # Legacy / unusual agents may expose ``provider`` directly on
+ # the Agent instead of via ``_model``; preserve the fallback.
+ legacy = getattr(agent, "provider", None)
+ if legacy is not None:
+ agent_providers = [legacy]
+ provider = agent_providers[0] if agent_providers else None
provider_detachers: list[Callable[[], None]] = []
def _subscribe(p: Any) -> None:
@@ -259,7 +268,8 @@ class Recorder:
# so a failed attach() leaves no dangling listeners. The caller never
# gets a ``detach`` callable on this path, so we cannot defer cleanup.
try:
- _subscribe(provider)
+ for p in agent_providers:
+ _subscribe(p)
# Middlewares may drive their own LLM calls (e.g.
# ``CompactionMiddleware``'s summarizer). For each declared
# (provider, model) pair: (a) subscribe the provider if we
@@ -288,7 +298,10 @@ class Recorder:
if agent_model is not None
else None
)
- seen: set[int] = {id(provider)} if provider is not None else set()
+ # Pre-seed `seen` with every chain provider already subscribed
+ # above so a middleware that reuses one of them isn't
+ # double-subscribed.
+ seen: set[int] = {id(p) for p in agent_providers}
for mw in getattr(agent, "_middleware", []) or []:
try:
extra = list(mw.extra_llm_calls())
diff --git a/tests/providers/test_fallback.py b/tests/providers/test_fallback.py
index 5556b36..b9c97de 100644
--- a/tests/providers/test_fallback.py
+++ b/tests/providers/test_fallback.py
@@ -372,3 +372,53 @@ async def test_generate_error_assistant_message_triggers_failover() -> None:
assert result.provider_id == "fallback"
assert result.stop_reason != "error"
+
+
+# ---------------------------------------------------------------------------
+# chain_providers helper — used by Recorder / Meter to subscribe to every
+# unique provider in a fallback chain (issue #167).
+# ---------------------------------------------------------------------------
+
+
+def test_chain_providers_for_fallback_returns_unique_providers_in_order() -> None:
+ """FallbackBoundModel chain → list of unique providers, primary first."""
+ from cubepi.providers.fallback import chain_providers
+
+ p1 = FauxProvider(provider_id="p1")
+ p2 = FauxProvider(provider_id="p2")
+ p3 = FauxProvider(provider_id="p3")
+ fbm = FallbackBoundModel(chain=(p1.model("a"), p2.model("b"), p3.model("c")))
+
+ out = chain_providers(fbm)
+ assert out == [p1, p2, p3]
+
+
+def test_chain_providers_dedupes_shared_provider_across_legs() -> None:
+ """Two chain entries on the same provider instance → single entry in output."""
+ from cubepi.providers.fallback import chain_providers
+
+ shared = FauxProvider(provider_id="shared")
+ other = FauxProvider(provider_id="other")
+ # primary + tertiary share the same provider; secondary differs.
+ fbm = FallbackBoundModel(
+ chain=(shared.model("a"), other.model("b"), shared.model("c"))
+ )
+
+ out = chain_providers(fbm)
+ assert out == [shared, other]
+
+
+def test_chain_providers_for_plain_bound_model_returns_single_entry() -> None:
+ """A plain BoundModel → single-entry list with its provider."""
+ from cubepi.providers.fallback import chain_providers
+
+ p = FauxProvider(provider_id="plain")
+ out = chain_providers(p.model("x"))
+ assert out == [p]
+
+
+def test_chain_providers_for_none_returns_empty() -> None:
+ """None model → empty list (used by attach()'s legacy fallback path)."""
+ from cubepi.providers.fallback import chain_providers
+
+ assert chain_providers(None) == []
diff --git a/tests/tracing/test_meter.py b/tests/tracing/test_meter.py
index aec2d6b..3f54088 100644
--- a/tests/tracing/test_meter.py
+++ b/tests/tracing/test_meter.py
@@ -348,3 +348,47 @@ class TestNoMetricsWithoutListeners:
points = _all_metric_points(reader)
assert _by_name(points, "gen_ai.client.operation.duration") == []
+
+
+class TestFallbackChainCoverage:
+ """Issue #167 — Meter.attach() should subscribe to every chain provider."""
+
+ async def test_attach_subscribes_to_every_chain_provider(self):
+ from cubepi.providers.fallback import FallbackBoundModel
+
+ primary = FauxProvider(provider_id="primary")
+ secondary = FauxProvider(provider_id="secondary")
+ chain_model = FallbackBoundModel(
+ chain=(primary.model(MODEL.id), secondary.model(MODEL.id)),
+ )
+ agent = Agent(model=chain_model, system_prompt="s")
+ meter, _ = _build_meter()
+ detach = meter.attach(agent)
+
+ # Both providers have request listeners registered.
+ assert len(getattr(primary, "_request_listeners", [])) == 1
+ assert len(getattr(secondary, "_request_listeners", [])) == 1
+
+ detach()
+
+ # Detach clears them.
+ assert len(getattr(primary, "_request_listeners", [])) == 0
+ assert len(getattr(secondary, "_request_listeners", [])) == 0
+
+ async def test_attach_dedupes_shared_provider_across_chain(self):
+ from cubepi.providers.fallback import FallbackBoundModel
+
+ shared = FauxProvider(provider_id="shared")
+ chain_model = FallbackBoundModel(
+ chain=(shared.model("m1"), shared.model("m2")),
+ )
+ agent = Agent(model=chain_model, system_prompt="s")
+ meter, _ = _build_meter()
+ detach = meter.attach(agent)
+
+ # Shared provider gets one listener of each kind, not two.
+ assert len(getattr(shared, "_request_listeners", [])) == 1
+ assert len(getattr(shared, "_chunk_listeners", [])) == 1
+ assert len(getattr(shared, "_response_listeners", [])) == 1
+
+ detach()
diff --git a/tests/tracing/test_recorder.py b/tests/tracing/test_recorder.py
index 82d006f..d08a504 100644
--- a/tests/tracing/test_recorder.py
+++ b/tests/tracing/test_recorder.py
@@ -1522,3 +1522,55 @@ class TestJsonlExporter:
d = _json.loads(line)
assert "name" in d
assert "context" in d
+
+
+class TestFallbackChainCoverage:
+ """Issue #167 — Tracer/Meter should subscribe to every chain provider."""
+
+ async def test_attach_subscribes_to_every_chain_provider(self):
+ """When agent.model is a FallbackBoundModel, attach() should listen
+ on each unique provider in chain — not just chain[0]."""
+ from cubepi.providers.fallback import FallbackBoundModel
+
+ primary = FauxProvider(provider_id="primary")
+ secondary = FauxProvider(provider_id="secondary")
+ chain_model = FallbackBoundModel(
+ chain=(primary.model(MODEL.id), secondary.model(MODEL.id)),
+ )
+ agent = Agent(model=chain_model, system_prompt="t")
+ exporter = InMemoryExporter()
+ tracer = Tracer(
+ service_name="t", agent_name="a", exporters=[exporter]
+ )
+ tracer.attach(agent)
+
+ recorder = _find_attached_recorder(primary)
+ assert recorder is not None, "primary leg must be subscribed"
+ recorder_2 = _find_attached_recorder(secondary)
+ assert recorder_2 is not None, "secondary leg must be subscribed"
+ # Both legs share the same Recorder instance.
+ assert recorder is recorder_2
+
+ await tracer.shutdown()
+
+ async def test_attach_dedupes_shared_provider_across_chain(self):
+ """If chain[0] and chain[1] share the same provider instance,
+ attach() must register listeners on it only once."""
+ from cubepi.providers.fallback import FallbackBoundModel
+
+ shared = FauxProvider(provider_id="shared")
+ chain_model = FallbackBoundModel(
+ chain=(shared.model("m1"), shared.model("m2")),
+ )
+ agent = Agent(model=chain_model, system_prompt="t")
+ exporter = InMemoryExporter()
+ tracer = Tracer(
+ service_name="t", agent_name="a", exporters=[exporter]
+ )
+ tracer.attach(agent)
+
+ # Each event type registered exactly once on the shared provider.
+ request_listeners = list(getattr(shared, "_request_listeners", []))
+ assert len(request_listeners) == 1, request_listeners
+
+ await tracer.shutdown()