nullrun 0.4.0__py3-none-any.whl

nullrun/instrumentation/langgraph.py

@@ -0,0 +1,412 @@
+"""
+LangGraph instrumentation primitives for NullRun SDK.
+
+This module ships the LangChain-compatible `NullRunCallback` —
+the low-level handler that:
+
+  1. Extracts `input_tokens` / `output_tokens` from LLM responses
+     and forwards them to the runtime's `track()` method (so the
+     backend can compute cost from the org's pricing policy).
+  2. Emits `span_start` / `span_end` events for chain / tool /
+     agent runs so the dashboard reconstructs the agent tree
+     (not just LLM cost). Nested runs become a parent/child span
+     tree via `parent_run_id` → active-span lookup.
+
+The user-facing helper that wires this callback onto a compiled
+LangGraph app lives at `nullrun.toolbox.langgraph.wrapper` (the
+manual escape hatch). For automatic attachment, see
+`nullrun.instrumentation.auto.patch_langgraph_compiled` — that
+is what `nullrun.init()` installs when `langgraph` is importable,
+so the user does NOT need to call `wrapper()` explicitly.
+
+Callers who want raw access to the callback can still import it
+from this module:
+
+    from nullrun.instrumentation.langgraph import NullRunCallback
+"""
+
+import logging
+from typing import Any
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+from nullrun.runtime import get_runtime
+from nullrun.tracing import (
+    SpanContext,
+    create_child_span,
+    create_root_span,
+    get_current_span,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Usage Normalization (SDK extracts, backend computes)
+# =============================================================================
+
+def extract_usage_from_response(response: Any, provider: str, model: str) -> dict[str, Any]:
+    """
+    Extract usage data from LLM response.
+
+    Returns raw usage dict - backend will normalize and compute cost.
+    SDK does NOT compute cost - this is intentional (backend is source of truth).
+
+    Returns:
+        Dict with keys:
+            - input_tokens: int
+            - output_tokens: int
+            - total_tokens: int
+            - has_usage: bool
+            - raw_usage: original dict from provider
+    """
+    usage: dict[str, Any] = {
+        "input_tokens": 0,
+        "output_tokens": 0,
+        "total_tokens": 0,
+        "has_usage": False,
+        "raw_usage": {},
+    }
+
+    # Try LangChain's usage_metadata first (most common for OpenAI via LangChain)
+    # NOTE: For callback-based invocation, response is LLMResult, not AIMessage
+    # LLMResult stores usage in generations[0][0].message.usage_metadata
+    if hasattr(response, 'usage_metadata'):
+        usage_meta = response.usage_metadata
+        if isinstance(usage_meta, dict):
+            usage["input_tokens"] = usage_meta.get('input_tokens', 0) or 0
+            usage["output_tokens"] = usage_meta.get('output_tokens', 0) or 0
+            usage["total_tokens"] = usage_meta.get('total_tokens', 0) or 0
+            usage["raw_usage"] = dict(usage_meta)
+        elif hasattr(usage_meta, 'input_tokens'):
+            # Object with attributes
+            usage["input_tokens"] = getattr(usage_meta, 'input_tokens', 0) or 0
+            usage["output_tokens"] = getattr(usage_meta, 'output_tokens', 0) or 0
+            usage["total_tokens"] = getattr(usage_meta, 'total_tokens', 0) or 0
+            usage["raw_usage"] = {
+                'input_tokens': usage["input_tokens"],
+                'output_tokens': usage["output_tokens"],
+                'total_tokens': usage["total_tokens"],
+            }
+
+    # For callback-based LLMResult, check generations[0][0].message.usage_metadata
+    elif hasattr(response, 'generations') and response.generations:
+        first_gen = response.generations[0][0] if response.generations else None
+        if first_gen and hasattr(first_gen, 'message'):
+            msg = first_gen.message
+            if hasattr(msg, 'usage_metadata'):
+                usage_meta = msg.usage_metadata
+                if isinstance(usage_meta, dict):
+                    usage["input_tokens"] = usage_meta.get('input_tokens', 0) or 0
+                    usage["output_tokens"] = usage_meta.get('output_tokens', 0) or 0
+                    usage["total_tokens"] = usage_meta.get('total_tokens', 0) or 0
+                    usage["raw_usage"] = dict(usage_meta)
+                elif hasattr(usage_meta, 'input_tokens'):
+                    usage["input_tokens"] = getattr(usage_meta, 'input_tokens', 0) or 0
+                    usage["output_tokens"] = getattr(usage_meta, 'output_tokens', 0) or 0
+                    usage["total_tokens"] = getattr(usage_meta, 'total_tokens', 0) or 0
+                    usage["raw_usage"] = {
+                        'input_tokens': usage["input_tokens"],
+                        'output_tokens': usage["output_tokens"],
+                        'total_tokens': usage["total_tokens"],
+                    }
+
+    # Try response.usage (Anthropic, standard OpenAI format)
+    elif hasattr(response, 'usage') and response.usage:
+        usage_raw = response.usage
+        if isinstance(usage_raw, dict):
+            usage["input_tokens"] = usage_raw.get('input_tokens', 0) or 0
+            usage["output_tokens"] = usage_raw.get('output_tokens', 0) or 0
+            usage["total_tokens"] = usage_raw.get('total_tokens', 0) or 0
+            usage["raw_usage"] = dict(usage_raw)
+        elif hasattr(usage_raw, 'input_tokens') or hasattr(usage_raw, 'total_tokens'):
+            # Object with attributes
+            usage["input_tokens"] = getattr(usage_raw, 'input_tokens', 0) or 0
+            usage["output_tokens"] = getattr(usage_raw, 'output_tokens', 0) or 0
+            usage["total_tokens"] = getattr(usage_raw, 'total_tokens', 0) or 0
+            usage["raw_usage"] = {
+                'input_tokens': usage["input_tokens"],
+                'output_tokens': usage["output_tokens"],
+                'total_tokens': usage["total_tokens"],
+            }
+
+    # Try response_metadata (some providers) - also check llm_output for LLMResult
+    elif hasattr(response, 'response_metadata'):
+        resp_meta = response.response_metadata
+        if isinstance(resp_meta, dict):
+            # Some providers put token info here
+            token_usage = resp_meta.get('token_usage', {})
+            if isinstance(token_usage, dict):
+                usage["input_tokens"] = (
+                    token_usage.get('prompt_tokens', 0) or
+                    token_usage.get('input_tokens', 0) or 0
+                )
+                usage["output_tokens"] = (
+                    token_usage.get('completion_tokens', 0) or
+                    token_usage.get('output_tokens', 0) or 0
+                )
+                usage["total_tokens"] = token_usage.get('total_tokens', 0) or 0
+                usage["raw_usage"] = dict(token_usage)
+    # Check llm_output for LLMResult (callback case)
+    elif hasattr(response, 'llm_output') and response.llm_output:
+        token_usage = response.llm_output.get('token_usage', {})
+        if isinstance(token_usage, dict):
+            usage["input_tokens"] = (
+                token_usage.get('prompt_tokens', 0) or
+                token_usage.get('input_tokens', 0) or 0
+            )
+            usage["output_tokens"] = (
+                token_usage.get('completion_tokens', 0) or
+                token_usage.get('output_tokens', 0) or 0
+            )
+            usage["total_tokens"] = token_usage.get('total_tokens', 0) or 0
+            usage["raw_usage"] = dict(token_usage)
+
+    # Check for streaming chunks that accumulated usage
+    # (streaming responses may not have usage until final chunk)
+    if not usage["has_usage"] and hasattr(response, '__iter__'):
+        # For streaming, we can't get accurate usage in middle of stream
+        # Final response should have usage_metadata
+        pass
+
+    # Determine if we got real usage data
+    usage["has_usage"] = (
+        usage["total_tokens"] > 0 or
+        usage["input_tokens"] > 0 or
+        usage["output_tokens"] > 0
+    )
+
+    return usage
+
+
+class NullRunCallback(BaseCallbackHandler):
+    """
+    LangChain-compatible callback handler for automatic tracking.
+
+    IMPORTANT: This callback extracts USAGE DATA only.
+    Cost computation happens in backend (source of truth).
+
+    Span emission: chain / tool / agent runs are wrapped in
+    `span_start` / `span_end` events so the dashboard reconstructs
+    the agent tree (not just LLM cost). Nested runs become a
+    parent/child span tree via `parent_run_id` -> active-span
+    lookup; if no parent is known, we fall back to the active
+    contextvar span (set by `@protect`) so a callback-driven chain
+    inside an `@protect`-wrapped function is properly nested.
+    """
+
+    def __init__(self, runtime: Any | None = None) -> None:
+        self.runtime = runtime or get_runtime()
+        # run_id -> SpanContext for in-flight chain / tool / agent
+        # runs. We use the LangChain run_id as the key because
+        # on_chain_end gives us the same run_id and we need to look
+        # up the corresponding span to emit span_end.
+        self._active_runs: dict[str, SpanContext] = {}
+
+    # ------------------------------------------------------------------
+    # LLM hooks (existing — token extraction only, no span bookkeeping)
+    # ------------------------------------------------------------------
+
+    def on_llm_start(self, serialized: Any, prompts: Any, **kwargs: Any) -> None:
+        """Called when LLM call starts."""
+        logger.debug(f"LLM start: {kwargs.get('invocation_params', {})}")
+
+    def on_llm_end(self, response: Any, **kwargs: Any) -> None:
+        """
+        Called when LLM call ends.
+
+        Extracts usage data and sends to backend for cost computation.
+        Does NOT compute cost - backend is source of truth.
+        """
+        try:
+            # Extract provider/model from invocation params
+            invocation_params = kwargs.get('invocation_params', {})
+            model = invocation_params.get('model_name', 'unknown')
+            provider = invocation_params.get('model_provider', 'openai')
+
+            # Extract usage (normalized format)
+            usage = extract_usage_from_response(response, provider, model)
+
+            logger.info(f"NullRun callback: model={model}, provider={provider}, "
+                      f"usage={usage}, has_usage={usage['has_usage']}")
+
+            # Build event with RAW usage data (no cost computation in SDK!)
+            event = {
+                "type": "llm_call",
+                "model": model,
+                "provider": provider,
+                "tokens": usage["total_tokens"],
+                "input_tokens": usage["input_tokens"],
+                "output_tokens": usage["output_tokens"],
+                # Flag to backend: this is raw usage, compute cost yourself
+                "has_usage": usage["has_usage"],
+                "raw_usage": usage["raw_usage"],
+            }
+
+            logger.info(f"NullRun track event: {event}")
+            self.runtime.track(event)
+
+            if usage["has_usage"]:
+                logger.debug(
+                    f"LLM tracked: model={model}, "
+                    f"tokens={usage['total_tokens']} "
+                    f"(in={usage['input_tokens']}, out={usage['output_tokens']})"
+                )
+            else:
+                logger.debug(f"LLM tracked: model={model}, NO usage data available")
+
+        except Exception as e:
+            logger.warning(f"Failed to track LLM event: {e}")
+
+    # ------------------------------------------------------------------
+    # Chain / tool / agent hooks — emit span events
+    # ------------------------------------------------------------------
+
+    def on_chain_start(
+        self,
+        serialized: Any,
+        inputs: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        """Open a chain span. Nested chains become child spans."""
+        if run_id is None:
+            # Defensive: some LangChain versions may omit run_id. We
+            # cannot emit a span we can later close without a key.
+            logger.debug("on_chain_start without run_id — skipping span emission")
+            return
+        name = _extract_node_name(serialized, "chain")
+        self._begin_run(str(run_id), str(parent_run_id) if parent_run_id else None,
+                        name, kind="chain")
+
+    def on_chain_end(self, outputs: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        self._end_run(run_id)
+
+    def on_chain_error(self, error: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        self._end_run(run_id, error=str(error))
+
+    def on_tool_start(
+        self,
+        serialized: Any,
+        input_str: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        """Open a tool span — function calls inside an agent."""
+        if run_id is None:
+            logger.debug("on_tool_start without run_id — skipping span emission")
+            return
+        name = _extract_node_name(serialized, "tool")
+        self._begin_run(str(run_id), str(parent_run_id) if parent_run_id else None,
+                        name, kind="tool")
+
+    def on_tool_end(self, output: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        self._end_run(run_id)
+
+    def on_tool_error(self, error: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        self._end_run(run_id, error=str(error))
+
+    def on_agent_action(
+        self,
+        action: Any,
+        *,
+        run_id: Any = None,
+        parent_run_id: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        """Agent reasoning step (ReAct / OpenAI Functions agent)."""
+        if run_id is None:
+            return
+        tool = getattr(action, "tool", None) or "agent"
+        self._begin_run(str(run_id), str(parent_run_id) if parent_run_id else None,
+                        f"agent_action:{tool}", kind="agent")
+
+    def on_agent_finish(self, finish: Any, *, run_id: Any = None, **kwargs: Any) -> None:
+        self._end_run(run_id)
+
+    # ------------------------------------------------------------------
+    # Span bookkeeping
+    # ------------------------------------------------------------------
+
+    def _begin_run(
+        self,
+        run_id: str,
+        parent_run_id: str | None,
+        name: str,
+        kind: str,
+    ) -> None:
+        """
+        Open a span for `run_id`, attached to the parent either via
+        the active-runs map (callback-internal nesting) or via the
+        SDK's `tracing` contextvar (set by `@protect`).
+
+        Span emission is best-effort — a failure here must never
+        break the user's chain. Mirrors the contract in
+        `nullrun.decorators._emit_span_start`.
+        """
+        parent_ctx: SpanContext | None = None
+        if parent_run_id:
+            parent_ctx = self._active_runs.get(parent_run_id)
+        if parent_ctx is None:
+            # Fall back to contextvar (e.g. we're inside an
+            # @protect-wrapped function or a manual `set_span`).
+            parent_ctx = get_current_span()
+        if parent_ctx is not None:
+            ctx = create_child_span(parent_ctx)
+        else:
+            ctx = create_root_span()
+        self._active_runs[run_id] = ctx
+        try:
+            self.runtime.track_event(
+                event_type="span_start",
+                trace_id=ctx.trace_id,
+                span_id=ctx.span_id,
+                parent_span_id=ctx.parent_span_id,
+                depth=ctx.depth,
+                fn_name=name,
+                span_kind=kind,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.debug(f"span_start emission failed: {exc}")
+
+    def _end_run(self, run_id: Any, error: str | None = None) -> None:
+        if run_id is None:
+            return
+        ctx = self._active_runs.pop(str(run_id), None)
+        if ctx is None:
+            return
+        try:
+            self.runtime.track_event(
+                event_type="span_end",
+                trace_id=ctx.trace_id,
+                span_id=ctx.span_id,
+                parent_span_id=ctx.parent_span_id,
+                depth=ctx.depth,
+                fn_name=None,
+                error=error,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.debug(f"span_end emission failed: {exc}")
+
+
+def _extract_node_name(serialized: Any, default: str) -> str:
+    """
+    Best-effort extraction of a friendly node name from a LangChain
+    `serialized` dict. Falls back to `default` if nothing readable.
+    """
+    if not isinstance(serialized, dict):
+        return default
+    ident = serialized.get("id")
+    if isinstance(ident, (list, tuple)) and ident:
+        return str(ident[-1])
+    if isinstance(ident, str):
+        return ident
+    name = serialized.get("name")
+    if isinstance(name, str):
+        return name
+    return default
+

nullrun/instrumentation/llama_index.py

@@ -0,0 +1,110 @@
+"""
+llama-index auto-instrumentation for NullRun SDK.
+
+Subscribes to the llama-index core event dispatcher (v0.10.20+) and
+emits ``llm_call`` events for every chat completion. Token usage is
+already captured by the httpx transport hook in ``auto.py`` — this
+patch is the safety net for cases where the dispatcher fires without
+a corresponding HTTP round-trip (e.g. tests, mock providers).
+
+Mirrors the structure of ``patch_langgraph_compiled`` in
+``auto.py:815-900``.
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_llama_index_patched = False
+_orig_subscriber_handlers: list[tuple[Any, Callable[..., Any]]] = []
+
+
+def patch_llama_index(runtime: Any) -> bool:
+    """Install NullRun subscribers on the llama-index core dispatcher.
+
+    Idempotent. Returns False if ``llama_index.core`` is not importable.
+    """
+    global _llama_index_patched
+    if _llama_index_patched:
+        return True
+    try:
+        from llama_index.core.instrumentation import get_dispatcher
+        from llama_index.core.instrumentation.events.llm import LLMChatEndEvent
+        from llama_index.core.instrumentation.events.tool import FunctionCallEvent
+    except ImportError:
+        logger.debug("llama-index not installed; auto-patch skipped")
+        return False
+
+    dispatcher = get_dispatcher(name="nullrun")
+
+    def on_chat_end(event: Any) -> None:
+        try:
+            usage = getattr(event.response, "raw", None) or {}
+            if hasattr(usage, "usage"):
+                usage = usage.usage or {}
+            prompt = int(usage.get("prompt_tokens", 0) or 0)
+            completion = int(usage.get("completion_tokens", 0) or 0)
+            total = int(usage.get("total_tokens", 0) or 0) or (prompt + completion)
+            if not (prompt or completion or total):
+                return
+            runtime.track(
+                {
+                    "type": "llm_call",
+                    "provider": "llama_index",
+                    "model": getattr(event.response, "model", None),
+                    "tokens": total,
+                    "input_tokens": prompt,
+                    "output_tokens": completion,
+                    "has_usage": True,
+                }
+            )
+        except Exception as e:  # pragma: no cover - defensive
+            logger.debug("llama_index on_chat_end: %s", e)
+
+    def on_function_call(event: Any) -> None:
+        try:
+            tool = getattr(event, "tool", None)
+            tool_name = getattr(tool, "name", None) or "tool"
+            runtime.track(
+                {
+                    "type": "tool_call",
+                    "tool_name": tool_name,
+                }
+            )
+        except Exception as e:  # pragma: no cover - defensive
+            logger.debug("llama_index on_function_call: %s", e)
+
+    dispatcher.add_event_handler(LLMChatEndEvent, on_chat_end)
+    dispatcher.add_event_handler(FunctionCallEvent, on_function_call)
+    _orig_subscriber_handlers.extend(
+        [
+            (LLMChatEndEvent, on_chat_end),
+            (FunctionCallEvent, on_function_call),
+        ]
+    )
+    _llama_index_patched = True
+    logger.info("llama-index auto-instrumentation installed")
+    return True
+
+
+def unpatch_llama_index() -> None:
+    """Detach our subscribers. Test-only. Idempotent."""
+    global _llama_index_patched
+    if not _llama_index_patched:
+        return
+    try:
+        from llama_index.core.instrumentation import get_dispatcher
+
+        dispatcher = get_dispatcher(name="nullrun")
+        for event_cls, handler in _orig_subscriber_handlers:
+            try:
+                dispatcher.remove_event_handler(event_cls, handler)
+            except Exception:  # pragma: no cover
+                pass
+    except ImportError:
+        pass
+    _orig_subscriber_handlers.clear()
+    _llama_index_patched = False

nullrun/observability.py

@@ -0,0 +1,160 @@
+"""
+NullRun observability — thread-safe in-process metrics counters.
+
+Exposes ``metrics`` for counter / gauge reporting; transport and runtime
+modules call into it for thread-safe increments. No external
+dependencies; integrate with Prometheus / OpenTelemetry on top.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from threading import Lock
+from typing import Any
+
+# ----------------------------------------------------------------
+# SDK Metrics (in-memory, no external dependencies)
+# ----------------------------------------------------------------
+
+@dataclass
+class TransportMetrics:
+    """Transport layer metrics. Reset on reset()."""
+    events_enqueued: int = 0
+    events_sent: int = 0
+    events_dropped: int = 0
+    batches_sent: int = 0
+    batches_failed: int = 0
+    retries_total: int = 0
+    circuit_breaker_opens: int = 0
+    last_flush_at: float | None = None
+    last_error: str | None = None
+    # Circuit breaker state transition metrics
+    circuit_open_count: int = 0
+    circuit_half_open_count: int = 0
+    circuit_closed_count: int = 0
+    fallback_mode_activations: int = 0
+    # Sprint 1.5 (B13): HMAC verification failures on the control
+    # plane WebSocket. Pre-fix, a signature mismatch on a signed
+    # ``state_change`` / ``key_rotated`` / ``policy_invalidated``
+    # message was logged at WARNING and the message was silently
+    # dropped — meaning a forged or mis-rotated kill command could
+    # be lost without a counter to alert on. The metric here is
+    # what a SRE alerts on for "control plane signature integrity".
+    hmac_verify_failures_total: int = 0
+
+
+@dataclass
+class RuntimeMetrics:
+    """Runtime layer metrics."""
+    track_calls: int = 0
+    execute_calls: int = 0
+    execute_allowed: int = 0
+    execute_blocked: int = 0
+    check_calls: int = 0
+    cost_limit_exceeded: int = 0
+    timeouts: int = 0
+    loop_detections: int = 0
+
+
+class MetricsRegistry:
+    """
+    Global SDK metrics registry.
+
+    Used for monitoring without external dependencies.
+    Can integrate with Prometheus or OpenTelemetry on top.
+
+    Thread-safe: All counter operations use locks to prevent race conditions
+    in multi-threaded environments.
+
+    Usage:
+        from nullrun.observability import metrics
+        print(metrics.transport.events_sent)
+        print(metrics.to_dict())
+
+        # Thread-safe increments (preferred over direct +=)
+        metrics.inc_transport("events_enqueued")
+        metrics.inc_transport("events_sent", 50)
+        metrics.inc_runtime("execute_calls")
+    """
+
+    def __init__(self) -> None:
+        self.transport = TransportMetrics()
+        self.runtime = RuntimeMetrics()
+        self._lock = Lock()
+
+    # ----------------------------------------------------------------
+    # Thread-safe metric increment methods
+    # ----------------------------------------------------------------
+
+    def inc_transport(self, field: str, value: int = 1) -> None:
+        """Thread-safe increment of transport metric counter.
+
+        Args:
+            field: Metric name (e.g., "events_enqueued", "batches_sent")
+            value: Amount to increment (default 1)
+        """
+        with self._lock:
+            current = getattr(self.transport, field, 0)
+            setattr(self.transport, field, current + value)
+
+    def inc_runtime(self, field: str, value: int = 1) -> None:
+        """Thread-safe increment of runtime metric counter.
+
+        Args:
+            field: Metric name (e.g., "track_calls", "execute_allowed")
+            value: Amount to increment (default 1)
+        """
+        with self._lock:
+            current = getattr(self.runtime, field, 0)
+            setattr(self.runtime, field, current + value)
+
+    def set_transport(self, field: str, value: Any) -> None:
+        """Thread-safe set of transport metric field.
+
+        Args:
+            field: Metric name (e.g., "last_error", "last_flush_at")
+            value: Value to set
+        """
+        with self._lock:
+            setattr(self.transport, field, value)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Export all metrics to dict. Convenient for /health endpoint."""
+        with self._lock:
+            return {
+                "transport": {
+                    "events_enqueued": self.transport.events_enqueued,
+                    "events_sent": self.transport.events_sent,
+                    "events_dropped": self.transport.events_dropped,
+                    "batches_sent": self.transport.batches_sent,
+                    "batches_failed": self.transport.batches_failed,
+                    "retries_total": self.transport.retries_total,
+                    "circuit_breaker_opens": self.transport.circuit_breaker_opens,
+                    "last_flush_at": self.transport.last_flush_at,
+                    "last_error": self.transport.last_error,
+                    "circuit_open_count": self.transport.circuit_open_count,
+                    "circuit_half_open_count": self.transport.circuit_half_open_count,
+                    "circuit_closed_count": self.transport.circuit_closed_count,
+                    "fallback_mode_activations": self.transport.fallback_mode_activations,
+                    "hmac_verify_failures_total": self.transport.hmac_verify_failures_total,
+                },
+                "runtime": {
+                    "track_calls": self.runtime.track_calls,
+                    "execute_calls": self.runtime.execute_calls,
+                    "execute_allowed": self.runtime.execute_allowed,
+                    "execute_blocked": self.runtime.execute_blocked,
+                    "cost_limit_exceeded": self.runtime.cost_limit_exceeded,
+                    "timeouts": self.runtime.timeouts,
+                    "loop_detections": self.runtime.loop_detections,
+                },
+            }
+
+    def reset(self) -> None:
+        """Reset all counters (useful in tests)."""
+        with self._lock:
+            self.transport = TransportMetrics()
+            self.runtime = RuntimeMetrics()
+
+
+# Global singleton registry
+metrics = MetricsRegistry()