PyPI - agent-observability-trace-cli - Versions diffs - 0.1.2__py3-none-any.whl - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (51) hide show

agent_observability_trace_cli-0.1.2.dist-info/METADATA +336 -0
agent_observability_trace_cli-0.1.2.dist-info/RECORD +51 -0
agent_observability_trace_cli-0.1.2.dist-info/WHEEL +4 -0
agent_observability_trace_cli-0.1.2.dist-info/entry_points.txt +2 -0
agent_observability_trace_cli-0.1.2.dist-info/licenses/LICENSE +198 -0
agent_trace/__init__.py +1182 -0
agent_trace/_cli.py +1377 -0
agent_trace/_inspect.py +2020 -0
agent_trace/_replay/__init__.py +1 -0
agent_trace/_replay/engine.py +268 -0
agent_trace/_replay/fixture.py +868 -0
agent_trace/core/__init__.py +1 -0
agent_trace/core/clock.py +91 -0
agent_trace/core/exceptions.py +51 -0
agent_trace/core/span.py +271 -0
agent_trace/core/trace.py +92 -0
agent_trace/exporters/__init__.py +1 -0
agent_trace/exporters/file.py +80 -0
agent_trace/exporters/otlp.py +199 -0
agent_trace/exporters/remote_fixture.py +307 -0
agent_trace/exporters/stdout.py +258 -0
agent_trace/integrations/__init__.py +69 -0
agent_trace/integrations/agno.py +489 -0
agent_trace/integrations/autogen.py +581 -0
agent_trace/integrations/crewai.py +486 -0
agent_trace/integrations/google_genai.py +731 -0
agent_trace/integrations/haystack.py +254 -0
agent_trace/integrations/langchain_core.py +361 -0
agent_trace/integrations/langgraph.py +2093 -0
agent_trace/integrations/langgraph_checkpoint.py +763 -0
agent_trace/integrations/langgraph_state_diff.py +345 -0
agent_trace/integrations/langgraph_stream_debug.py +202 -0
agent_trace/integrations/llama_index.py +472 -0
agent_trace/integrations/mcp.py +281 -0
agent_trace/integrations/openai_agents.py +811 -0
agent_trace/integrations/pydantic_ai.py +504 -0
agent_trace/integrations/streaming.py +218 -0
agent_trace/interceptor/__init__.py +64 -0
agent_trace/interceptor/aiohttp_hook.py +152 -0
agent_trace/interceptor/botocore_hook.py +223 -0
agent_trace/interceptor/grpc_hook.py +651 -0
agent_trace/interceptor/httpx_hook.py +866 -0
agent_trace/interceptor/logging_hook.py +137 -0
agent_trace/interceptor/requests_patch.py +184 -0
agent_trace/interceptor/sse.py +176 -0
agent_trace/interceptor/stdio_hook.py +245 -0
agent_trace/interceptor/warnings_hook.py +132 -0
agent_trace/interceptor/websocket_hook.py +323 -0
agent_trace/plugins/__init__.py +35 -0
agent_trace/plugins/base.py +111 -0
agent_trace/py.typed +0 -0

agent_trace/exporters/stdout.py ADDED Viewed

@@ -0,0 +1,258 @@
+"""
+Console exporter — prints a trace as a colored span tree using rich.
+Falls back to plain text if rich is not installed.
+"""
+from __future__ import annotations
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+if TYPE_CHECKING:
+    from agent_trace import Span, Trace
+__all__ = [
+    "StdoutExporter",
+    "export",
+]
+# Colour map: SpanStatus value -> rich colour name
+_STATUS_COLOUR: dict[str, str] = {
+    "OK": "green",
+    "ERROR": "red",
+    "UNSET": "yellow",
+}
+# Plain-text symbol map
+_STATUS_SYMBOL: dict[str, str] = {
+    "OK": "[OK]",
+    "ERROR": "[ERR]",
+    "UNSET": "[---]",
+}
+# Span attributes worth surfacing inline in the tree view — the two numbers
+# needed to check "did latency grow along with prompt size across turns"
+# (#2920) are otherwise only reachable by manually opening trace.json and
+# cross-referencing two separate JSON keys per span.
+_INLINE_ATTRIBUTE_KEYS: tuple[str, ...] = (
+    "llm.model",
+    "llm.usage.prompt_tokens",
+    "llm.usage.completion_tokens",
+    "llm.usage.total_tokens",
+)
+def _inline_attributes_suffix(attributes: Mapping[str, object]) -> str:
+    """Render a compact ``key=value`` suffix for the subset of *attributes*
+    worth showing inline, or "" if none of them are present."""
+    parts = [
+        f"{key}={attributes[key]}"
+        for key in _INLINE_ATTRIBUTE_KEYS
+        if key in attributes
+    ]
+    return f"  ({', '.join(parts)})" if parts else ""
+def _exception_message(span: Span) -> str | None:
+    """Return the exception.message text captured on *span* via
+    Span.record_exception(), or None if it has no recorded exception event
+    — the data Span.record_exception() (core/span.py) already captures on
+    every ERROR span, but which was previously invisible in this tree view
+    (a developer saw "[ERR] llm:<model>" with no indication of why)."""
+    for event in span.events:
+        if event.name == "exception" and "exception.message" in event.attributes:
+            return str(event.attributes["exception.message"])
+    return None
+def _unaccounted_ms(span: Span, children: list[Span] | None) -> float | None:
+    """Return *span*'s duration_ms minus the sum of its direct children's
+    duration_ms, or None when it can't be computed (span or any child is
+    still open, or there are no children — nothing to subtract).
+    Surfaces the gap a developer previously had to manually eyeball —
+    "this node took far longer than the LLM call inside it did" — e.g.
+    #2920's reporters posting screenshots of exactly this pattern with no
+    quantified figure to point at.
+    """
+    if span.duration_ms is None or not children:
+        return None
+    child_total = 0.0
+    for child in children:
+        if child.duration_ms is None:
+            return None  # a still-open child makes the subtraction meaningless
+        child_total += child.duration_ms
+    return span.duration_ms - child_total
+def _unaccounted_suffix(span: Span, children: list[Span] | None) -> str:
+    unaccounted = _unaccounted_ms(span, children)
+    if unaccounted is None:
+        return ""
+    return f"  [{unaccounted:.1f}ms unaccounted of {span.duration_ms:.1f}ms]"
+def _exception_http_detail(span: Span) -> str | None:
+    """Return "HTTP <status>: <body preview>" when *span*'s recorded
+    exception carried an HTTP error response body (exception.http_
+    response_body/exception.http_status_code, set by Span.record_exception
+    for requests.exceptions.HTTPError/httpx.HTTPStatusError-shaped
+    exceptions) — the actual provider/proxy error text (#4940), which
+    str(exc) alone (all `_exception_message` surfaces) typically omits."""
+    for event in span.events:
+        if event.name != "exception":
+            continue
+        body = event.attributes.get("exception.http_response_body")
+        if not body:
+            continue
+        status = event.attributes.get("exception.http_status_code")
+        prefix = f"HTTP {status}: " if status is not None else "HTTP: "
+        return f"{prefix}{body}"
+    return None
+def _trace_header_info(trace: Trace) -> tuple[str, str]:
+    """Return (duration_string, display_name) for trace header lines."""
+    ended = [s.end_time for s in trace.spans if s.end_time is not None]
+    started = [s.start_time for s in trace.spans]
+    dur_str = ""
+    if started and ended:
+        total_ms = (max(ended) - min(started)) * 1_000
+        dur_str = f" ({total_ms:.1f} ms total)"
+    display_name = str(trace.metadata.get("name", trace.run_id))
+    return dur_str, display_name
+class StdoutExporter:
+    """Export a :class:`~agent_trace.Trace` as a human-readable span tree.
+    Uses ``rich`` for coloured output when available; otherwise falls back to
+    plain indented ASCII.
+    """
+    def export(self, trace: Trace) -> None:
+        """Print the full span tree for *trace* to stdout."""
+        try:
+            self._export_rich(trace)
+        except ImportError:
+            self._export_plain(trace)
+    def export_span(
+        self, span: Span, depth: int = 0, children: list[Span] | None = None
+    ) -> None:
+        """Export a single span at the given indent depth (plain-text only).
+        *children*, when supplied, enables the "N ms unaccounted of M ms
+        total" suffix (duration_ms minus the sum of direct children's
+        duration_ms) — omitted entirely when not supplied, so existing
+        single-span callers are unaffected.
+        """
+        indent = "  " * depth
+        sym = _STATUS_SYMBOL.get(span.status.value, "[---]")
+        dur = f" ({span.duration_ms:.1f} ms)" if span.duration_ms is not None else ""
+        attrs_suffix = _inline_attributes_suffix(span.attributes)
+        unaccounted_suffix = _unaccounted_suffix(span, children)
+        print(f"{indent}{sym} {span.name}{dur}{attrs_suffix}{unaccounted_suffix}")
+        if span.status.value == "ERROR":
+            message = _exception_message(span)
+            if message:
+                print(f"{indent}      ! {message}")
+            http_detail = _exception_http_detail(span)
+            if http_detail:
+                print(f"{indent}      ! {http_detail}")
+    # ------------------------------------------------------------------
+    # Rich implementation
+    # ------------------------------------------------------------------
+    def _export_rich(self, trace: Trace) -> None:
+        from rich.console import Console
+        from rich.tree import Tree
+        console = Console()
+        dur_str, display_name = _trace_header_info(trace)
+        rich_dur = f"  [dim]({dur_str.strip()})[/dim]" if dur_str else ""
+        root_label = (
+            f"[bold cyan]Trace:[/bold cyan] {display_name}"
+            f"  [dim]{trace.run_id}[/dim]{rich_dur}"
+        )
+        tree = Tree(root_label)
+        # Build parent->children map first so tree construction is order-independent.
+        children_map: dict[str | None, list[Any]] = {}
+        for span in trace.spans:
+            children_map.setdefault(span.parent_id, []).append(span)
+        def _add_children(parent_node: Any, parent_id: str | None) -> None:
+            for span in children_map.get(parent_id, []):
+                colour = _STATUS_COLOUR.get(span.status.value, "yellow")
+                dur = (
+                    f"  [dim]({span.duration_ms:.1f} ms)[/dim]"
+                    if span.duration_ms is not None
+                    else ""
+                )
+                attrs_suffix = _inline_attributes_suffix(span.attributes)
+                dim_attrs = (
+                    f"  [dim]{attrs_suffix.strip()}[/dim]" if attrs_suffix else ""
+                )
+                unaccounted_suffix = _unaccounted_suffix(
+                    span, children_map.get(span.span_id)
+                )
+                dim_unaccounted = (
+                    f"  [dim]{unaccounted_suffix.strip()}[/dim]"
+                    if unaccounted_suffix
+                    else ""
+                )
+                label = (
+                    f"[{colour}]{span.name}[/{colour}]"
+                    f"  [{colour}]{span.status.value}[/{colour}]"
+                    f"{dur}{dim_attrs}{dim_unaccounted}"
+                )
+                if span.status.value == "ERROR":
+                    message = _exception_message(span)
+                    if message:
+                        label += f"\n  [red]! {message}[/red]"
+                    http_detail = _exception_http_detail(span)
+                    if http_detail:
+                        label += f"\n  [red]! {http_detail}[/red]"
+                node = parent_node.add(label)
+                _add_children(node, span.span_id)
+        _add_children(tree, None)
+        console.print(tree)
+    # ------------------------------------------------------------------
+    # Plain-text fallback
+    # ------------------------------------------------------------------
+    def _export_plain(self, trace: Trace) -> None:
+        dur_str, display_name = _trace_header_info(trace)
+        print(f"Trace: {display_name}  [{trace.run_id}]{dur_str}")
+        # Build parent->children mapping for tree printing
+        children: dict[str | None, list[Span]] = {}
+        for span in trace.spans:
+            children.setdefault(span.parent_id, []).append(span)
+        def _print_subtree(parent_id: str | None, depth: int) -> None:
+            for span in children.get(parent_id, []):
+                self.export_span(
+                    span, depth=depth, children=children.get(span.span_id)
+                )
+                _print_subtree(span.span_id, depth + 1)
+        _print_subtree(None, depth=1)
+# ---------------------------------------------------------------------------
+# Module-level convenience
+# ---------------------------------------------------------------------------
+_default_exporter: StdoutExporter = StdoutExporter()
+def export(trace: Trace) -> None:
+    """Export *trace* to stdout using the default :class:`StdoutExporter`."""
+    _default_exporter.export(trace)

agent_trace/integrations/__init__.py ADDED Viewed

@@ -0,0 +1,69 @@
+"""
+agent-trace framework integrations.
+Each submodule wraps a specific agent framework's callback/event-hook
+surface to emit agent-trace spans (e.g. ``langgraph.py`` for LangGraph,
+``openai_agents.py`` for the OpenAI Agents SDK, ``crewai.py`` for crewAI).
+Submodules are exported lazily here (PEP 562 module ``__getattr__``) so that
+``import agent_trace.integrations`` never fails regardless of which optional
+framework SDKs happen to be installed — none of the submodules themselves
+import their target SDK at module import time either (see langgraph.py /
+openai_agents.py, which defer the real ``import langgraph`` / ``import
+agents`` to call time inside the class/function that needs it). Accessing a
+specific submodule (e.g. ``agent_trace.integrations.crewai`` or ``from
+agent_trace.integrations import crewai``) triggers that submodule's own
+import; only *calling* something inside it that actually needs the SDK
+raises a helpful ``ImportError`` with an install hint if the SDK is
+missing.
+"""
+from __future__ import annotations
+import importlib
+from typing import TYPE_CHECKING, Any
+if TYPE_CHECKING:
+    from agent_trace.integrations import (
+        agno,
+        autogen,
+        crewai,
+        google_genai,
+        haystack,
+        langgraph,
+        langgraph_checkpoint,
+        langgraph_state_diff,
+        langgraph_stream_debug,
+        llama_index,
+        mcp,
+        openai_agents,
+        pydantic_ai,
+        streaming,
+    )
+__all__ = [
+    "agno",
+    "autogen",
+    "crewai",
+    "google_genai",
+    "haystack",
+    "langgraph",
+    "langgraph_checkpoint",
+    "langgraph_state_diff",
+    "langgraph_stream_debug",
+    "llama_index",
+    "mcp",
+    "openai_agents",
+    "pydantic_ai",
+    "streaming",
+]
+def __getattr__(name: str) -> Any:
+    if name in __all__:
+        return importlib.import_module(f"agent_trace.integrations.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+def __dir__() -> list[str]:
+    return sorted(__all__)