agent-observability-trace-cli 0.1.2__py3-none-any.whl

agent_trace/core/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

agent_trace/core/clock.py

@@ -0,0 +1,91 @@
+"""
+Clock abstraction for deterministic replay.
+
+All spans use get_time() from this module — never time.time() directly.
+During replay, set_clock(FixtureClock()) swaps the time source so all
+recorded timestamps are replayed exactly without wall-clock drift.
+"""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from contextvars import ContextVar, Token
+
+__all__ = [
+    "Clock",
+    "FixtureClock",
+    "WallClock",
+    "get_clock",
+    "get_time",
+    "restore_clock",
+    "set_clock",
+]
+
+
+class Clock(ABC):
+    """Abstract base for all time sources used by agent-trace spans."""
+
+    @abstractmethod
+    def now(self) -> float:
+        """Return current time as a Unix timestamp (seconds since epoch)."""
+        ...
+
+
+class WallClock(Clock):
+    """Production clock that delegates to time.time()."""
+
+    def now(self) -> float:
+        return time.time()
+
+
+class FixtureClock(Clock):
+    """Replay clock driven by pre-recorded timestamps.
+
+    Initialises to ``time.time()`` so replay spans have meaningful timestamps
+    by default.  Call :meth:`advance` with each recorded timestamp to reproduce
+    original execution times exactly.
+    """
+
+    def __init__(self, initial: float | None = None) -> None:
+        self._current: float = initial if initial is not None else time.time()
+
+    def advance(self, timestamp: float) -> None:
+        """Set the clock to *timestamp* (seconds since epoch)."""
+        self._current = timestamp
+
+    def now(self) -> float:
+        return self._current
+
+
+# One clock per async context (or thread).  Default is the real wall clock so
+# that code works without any setup in production.
+_clock_var: ContextVar[Clock] = ContextVar("_agent_trace_clock", default=WallClock())  # noqa: B039
+
+
+def get_clock() -> Clock:
+    """Return the active Clock for the current context."""
+    return _clock_var.get()
+
+
+def set_clock(clock: Clock) -> Token[Clock]:
+    """Replace the active clock and return a Token for later restoration.
+
+    Always pair with restore_clock() in a finally block to avoid leaking the
+    override into sibling async tasks.
+    """
+    return _clock_var.set(clock)
+
+
+def restore_clock(token: Token[Clock]) -> None:
+    """Undo a previous set_clock() using the Token it returned."""
+    _clock_var.reset(token)
+
+
+def get_time() -> float:
+    """Return current time from the active clock.
+
+    This is the only call-site for time inside agent-trace core code.  Using
+    this instead of time.time() directly is what makes replay deterministic.
+    """
+    return _clock_var.get().now()

agent_trace/core/exceptions.py

@@ -0,0 +1,51 @@
+"""
+Shared exception types for agent-trace.
+
+Centralised here so that callers can catch a single NetworkGuardError
+regardless of which HTTP client (httpx or requests) raised it.
+"""
+
+from __future__ import annotations
+
+import os
+
+__all__ = ["NetworkGuardError", "RunawayToolCallLoopError", "guard_active"]
+
+
+class NetworkGuardError(RuntimeError):
+    """Raised when a live network call is attempted during guarded replay.
+
+    Set ``AGENT_TRACE_NETWORK_GUARD=1`` to activate the guard.  The guard
+    exists so that test suites relying on fixtures blow up loudly rather than
+    silently hitting real endpoints, which would cause non-deterministic
+    results and unexpected API costs.
+
+    Both the httpx and requests interceptors raise this same class, so a
+    single ``except NetworkGuardError`` catches either.
+    """
+
+
+class RunawayToolCallLoopError(RuntimeError):
+    """Raised by RecordingTransport/AsyncRecordingTransport's optional
+    live loop guard (``loop_guard_threshold=``) once a configurable number
+    of *consecutive* tool-call-only responses have been recorded for the
+    same host during an active recording session.
+
+    This is the live-recording signal for issue #3097 — a model that never
+    stops emitting ``tool_calls`` and never returns a final tool-call-free
+    message, silently burning through the full context window (and API
+    budget) before anyone notices. Replay-after-the-fact only helps
+    diagnose a loop that already happened and already cost the tokens; this
+    guard is what actually catches it early, during the run that is still
+    burning the budget.
+
+    Raised (rather than merely warned) only when the transport was
+    constructed with ``on_loop_detected=agent_trace.interceptor.httpx_hook.
+    raise_on_loop_detected`` (or an equivalent custom callback) — the
+    default ``on_loop_detected`` only emits a ``UserWarning``.
+    """
+
+
+def guard_active() -> bool:
+    """Return True when AGENT_TRACE_NETWORK_GUARD=1 is set in the environment."""
+    return os.environ.get("AGENT_TRACE_NETWORK_GUARD", "0") == "1"

agent_trace/core/span.py

@@ -0,0 +1,271 @@
+"""
+Span and SpanEvent data models for agent-trace.
+
+A Span represents a single unit of work within a trace.  Spans are cheap
+value objects — they hold no locks, no background threads, and no file
+handles.  All mutation goes through the public methods below so that
+to_dict() remains consistent with the live state.
+"""
+
+from __future__ import annotations
+
+import traceback
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from agent_trace.core.clock import get_time
+
+__all__ = [
+    "Span",
+    "SpanEvent",
+    "SpanStatus",
+]
+
+# Attribute value types accepted everywhere in this module.
+_AttrValue = str | int | float | bool
+
+# Matches the truncation length used for other large captured text
+# attributes (see agent_trace.integrations.langgraph._MAX_ATTR_LEN) so a
+# pathologically large error body can't blow up trace.json.
+_MAX_EXCEPTION_RESPONSE_BODY_LEN = 8_000
+
+
+def _http_error_response_body(exc: BaseException) -> tuple[str | None, int | None]:
+    """Best-effort extraction of ``(response_text, status_code)`` from an
+    exception exposing a ``.response`` attribute — the shape
+    ``requests.exceptions.HTTPError``, ``httpx.HTTPStatusError``, and
+    similar HTTP-error-carrying exceptions across provider SDKs all follow.
+
+    Returns ``(None, None)`` for anything that doesn't match — this must
+    never raise, since it runs inside exception-handling code itself.
+    """
+    try:
+        response = getattr(exc, "response", None)
+    except Exception:
+        return None, None
+    if response is None:
+        return None, None
+
+    status_code: Any = None
+    try:
+        status_code = getattr(response, "status_code", None)
+        if status_code is None:
+            # requests uses `.status_code`; some SDKs expose it differently.
+            status_code = getattr(response, "status", None)
+    except Exception:
+        status_code = None
+
+    text: str | None = None
+    try:
+        raw_text = getattr(response, "text", None)
+        if isinstance(raw_text, str):
+            text = raw_text
+        elif callable(raw_text):
+            # Some response-like objects expose text() as a method.
+            maybe = raw_text()
+            if isinstance(maybe, str):
+                text = maybe
+    except Exception:
+        text = None
+
+    if text is None:
+        try:
+            content = getattr(response, "content", None)
+            if isinstance(content, bytes):
+                text = content.decode("utf-8", errors="replace")
+            elif isinstance(content, str):
+                text = content
+        except Exception:
+            text = None
+
+    if text is not None and len(text) > _MAX_EXCEPTION_RESPONSE_BODY_LEN:
+        text = text[:_MAX_EXCEPTION_RESPONSE_BODY_LEN] + "...<truncated>"
+
+    return text, status_code if isinstance(status_code, int) else None
+
+
+class SpanStatus(str, Enum):
+    """Lifecycle status of a Span, modelled after OpenTelemetry's StatusCode.
+
+    CANCELLED is deliberately distinct from ERROR: a span ended because the
+    run/task it belonged to was cancelled (e.g. ``asyncio.CancelledError``)
+    did not fail — it was cut off mid-flight. Collapsing both into ERROR
+    makes a genuine application failure indistinguishable from a cancelled
+    run when reading a trace, which matters for diagnosing
+    cancellation-triggered data-loss bugs (e.g. unpersisted checkpoints).
+    """
+
+    UNSET = "UNSET"
+    OK = "OK"
+    ERROR = "ERROR"
+    CANCELLED = "CANCELLED"
+
+
+@dataclass
+class SpanEvent:
+    """A timestamped annotation attached to a Span.
+
+    Events capture point-in-time occurrences (e.g. "tool call returned") that
+    are too fine-grained for their own span.
+    """
+
+    name: str
+    timestamp: float
+    attributes: dict[str, _AttrValue] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "timestamp": self.timestamp,
+            "attributes": dict(self.attributes),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SpanEvent:
+        return cls(
+            name=str(data["name"]),
+            timestamp=float(data["timestamp"]),
+            attributes=dict(data.get("attributes", {})),
+        )
+
+
+@dataclass
+class Span:
+    """Immutable-by-convention record of a single traced operation.
+
+    Spans are created open (end_time is None) and closed via end().  After
+    end() is called, the span should be treated as read-only — mutating a
+    closed span produces undefined behaviour in exporters.
+
+    All timestamps come from core.clock.get_time() so the replay engine can
+    substitute pre-recorded values without touching any other code.
+    """
+
+    span_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    trace_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    parent_id: str | None = None
+    name: str = ""
+    start_time: float = field(default_factory=get_time)
+    end_time: float | None = None
+    status: SpanStatus = SpanStatus.UNSET
+    attributes: dict[str, _AttrValue] = field(default_factory=dict)
+    events: list[SpanEvent] = field(default_factory=list)
+
+    # ------------------------------------------------------------------
+    # Mutation helpers
+    # ------------------------------------------------------------------
+
+    def end(self, status: SpanStatus = SpanStatus.OK) -> None:
+        """Close the span, recording end_time and setting status."""
+        if self.end_time is not None:
+            return
+        self.end_time = get_time()
+        self.status = status
+
+    def add_event(
+        self,
+        name: str,
+        attributes: dict[str, _AttrValue] | None = None,
+    ) -> None:
+        """Append a named event at the current clock time."""
+        self.events.append(
+            SpanEvent(
+                name=name,
+                timestamp=get_time(),
+                attributes=attributes or {},
+            )
+        )
+
+    def set_attribute(self, key: str, value: _AttrValue) -> None:
+        """Set or overwrite a single attribute."""
+        self.attributes[key] = value
+
+    def record_exception(
+        self, exc: BaseException, status: SpanStatus = SpanStatus.ERROR
+    ) -> None:
+        """Capture an exception as a SpanEvent and mark the span's status.
+
+        Follows OpenTelemetry's exception semantic conventions so downstream
+        exporters (e.g. the OTLP exporter) can surface the stack trace.
+
+        ``status`` defaults to ``SpanStatus.ERROR`` (the historical
+        behavior). Pass ``status=SpanStatus.CANCELLED`` for a span ended by
+        run/task cancellation so a reader of the trace can tell "this
+        failed" apart from "this was cut off mid-flight".
+        """
+        attributes: dict[str, _AttrValue] = {
+            "exception.type": type(exc).__qualname__,
+            "exception.message": str(exc),
+            "exception.stacktrace": "".join(
+                traceback.format_exception(type(exc), exc, exc.__traceback__)
+            ),
+        }
+
+        # requests.exceptions.HTTPError / httpx.HTTPStatusError / similar
+        # HTTP-error-carrying exceptions stringify to a generic one-liner
+        # (e.g. "400 Client Error: None for url: ...") that omits the
+        # actual provider/proxy error body — attach it explicitly so the
+        # span view alone is enough to root-cause the failure, without
+        # falling back to manually grepping fixture.db.
+        response_text, status_code = _http_error_response_body(exc)
+        if response_text is not None:
+            attributes["exception.http_response_body"] = response_text
+        if status_code is not None:
+            attributes["exception.http_status_code"] = status_code
+
+        self.add_event("exception", attributes=attributes)
+        self.status = status
+
+    # ------------------------------------------------------------------
+    # Computed properties
+    # ------------------------------------------------------------------
+
+    @property
+    def duration_ms(self) -> float | None:
+        """Wall duration in milliseconds, or None if the span is still open."""
+        if self.end_time is None:
+            return None
+        return (self.end_time - self.start_time) * 1_000
+
+    # ------------------------------------------------------------------
+    # Serialisation — all primitives, no datetime objects
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a JSON-safe dict.
+
+        Enums are stored by value so the output is readable without importing
+        this module.  Timestamps are plain floats (Unix seconds) to avoid
+        timezone ambiguity and datetime import overhead.
+        """
+        return {
+            "span_id": self.span_id,
+            "trace_id": self.trace_id,
+            "parent_id": self.parent_id,
+            "name": self.name,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "status": self.status.value,
+            "attributes": dict(self.attributes),
+            "events": [e.to_dict() for e in self.events],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Span:
+        """Deserialise from a dict produced by to_dict()."""
+        events = [SpanEvent.from_dict(e) for e in data.get("events", [])]
+        return cls(
+            span_id=str(data["span_id"]),
+            trace_id=str(data["trace_id"]),
+            parent_id=data.get("parent_id"),
+            name=str(data["name"]),
+            start_time=float(data["start_time"]),
+            end_time=float(data["end_time"])
+            if data.get("end_time") is not None
+            else None,
+            status=SpanStatus(data.get("status", SpanStatus.UNSET.value)),
+            attributes=dict(data.get("attributes", {})),
+            events=events,
+        )

agent_trace/core/trace.py

@@ -0,0 +1,92 @@
+"""
+Trace — a collection of Spans sharing a single trace_id.
+
+A Trace is the top-level container returned by the tracer and persisted to
+disk.  It intentionally holds no locks or I/O handles; thread-safety is the
+responsibility of the Tracer that creates and mutates it.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from agent_trace.core.span import Span, _AttrValue
+
+__all__ = ["Trace"]
+
+
+@dataclass
+class Trace:
+    """Ordered collection of Spans that belong to one logical agent run.
+
+    ``run_id`` identifies the *execution* (re-running the same code produces
+    a new run_id) while ``trace_id`` identifies the *trace structure* — the
+    same fixture can be replayed many times with different run_ids but the
+    same trace_id so that tooling can diff runs.
+    """
+
+    trace_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    run_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    spans: list[Span] = field(default_factory=list)
+    metadata: dict[str, _AttrValue] = field(default_factory=dict)
+
+    # ------------------------------------------------------------------
+    # Mutation helpers
+    # ------------------------------------------------------------------
+
+    def add_span(self, span: Span) -> None:
+        """Append *span* to this trace, enforcing trace_id consistency.
+
+        If the span carries a different trace_id it means it was created
+        before the trace existed (e.g. during library initialisation).  We
+        silently correct the mismatch so callers don't need to thread
+        trace_id through every call-site.
+        """
+        if span.trace_id != self.trace_id:
+            span.trace_id = self.trace_id
+        self.spans.append(span)
+
+    # ------------------------------------------------------------------
+    # Queries
+    # ------------------------------------------------------------------
+
+    def get_span(self, span_id: str) -> Span | None:
+        """Return the first span whose span_id matches, or None."""
+        for span in self.spans:
+            if span.span_id == span_id:
+                return span
+        return None
+
+    def root_spans(self) -> list[Span]:
+        """Return spans that have no parent (top-level operations)."""
+        return [s for s in self.spans if s.parent_id is None]
+
+    def children_of(self, span_id: str) -> list[Span]:
+        """Return all direct children of *span_id* in insertion order."""
+        return [s for s in self.spans if s.parent_id == span_id]
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a JSON-safe dict (no datetime objects, enums by value)."""
+        return {
+            "trace_id": self.trace_id,
+            "run_id": self.run_id,
+            "spans": [s.to_dict() for s in self.spans],
+            "metadata": dict(self.metadata),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Trace:
+        """Deserialise from a dict produced by to_dict()."""
+        spans = [Span.from_dict(s) for s in data.get("spans", [])]
+        return cls(
+            trace_id=str(data["trace_id"]),
+            run_id=str(data["run_id"]),
+            spans=spans,
+            metadata={k: v for k, v in data.get("metadata", {}).items()},
+        )

agent_trace/exporters/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

agent_trace/exporters/file.py

@@ -0,0 +1,80 @@
+"""
+File exporter — writes traces as JSON or JSONL files.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from agent_trace import Trace
+
+__all__ = [
+    "FileExporter",
+    "export",
+]
+
+
+class FileExporter:
+    """Write a :class:`~agent_trace.Trace` to disk as JSON or JSONL.
+
+    Parameters
+    ----------
+    output_dir:
+        Directory where trace files are written.  Created if it does not exist.
+    format:
+        ``"json"`` writes a single pretty-printed JSON file with the full
+        trace structure.  ``"jsonl"`` writes one span dict per line.
+    """
+
+    def __init__(
+        self,
+        output_dir: Path,
+        format: Literal["json", "jsonl"] = "json",
+    ) -> None:
+        self.output_dir: Path = Path(output_dir)
+        self.format: Literal["json", "jsonl"] = format
+
+    def export(self, trace: Trace) -> Path:
+        """Write *trace* to ``output_dir/{run_id}.{format}`` and return the path."""
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        base = self.output_dir.resolve()
+        out_path = (base / f"{trace.run_id}.{self.format}").resolve()
+        try:
+            out_path.relative_to(base)
+        except ValueError:
+            raise ValueError(
+                f"Invalid run_id {trace.run_id!r}: path traversal detected"
+            ) from None
+
+        if self.format == "jsonl":
+            lines = [
+                json.dumps(span.to_dict(), separators=(",", ":"))
+                for span in trace.spans
+            ]
+            out_path.write_text(
+                "\n".join(lines) + ("\n" if lines else ""), encoding="utf-8"
+            )
+        else:
+            out_path.write_text(json.dumps(trace.to_dict(), indent=2), encoding="utf-8")
+
+        return out_path
+
+
+# ---------------------------------------------------------------------------
+# Module-level convenience
+# ---------------------------------------------------------------------------
+
+
+def export(
+    trace: Trace,
+    output_dir: Path | None = None,
+) -> Path:
+    """Export *trace* as JSON to *output_dir* (default: current directory).
+
+    Returns the path of the written file.
+    """
+    effective_dir = output_dir or Path.cwd()
+    return FileExporter(effective_dir).export(trace)