asap-protocol 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

asap/observability/trace_parser.py

@@ -0,0 +1,238 @@
+"""Trace parsing and ASCII visualization from ASAP structured logs.
+
+Parses JSON log lines containing asap.request.received and asap.request.processed
+events, filters by trace_id, and builds a request flow with timing for CLI output.
+
+Expected log events (from transport/server.py):
+- asap.request.received: envelope_id, trace_id, sender, recipient, payload_type
+- asap.request.processed: envelope_id, trace_id, duration_ms, payload_type
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Iterable
+
+# Event names emitted by ASAP server
+EVENT_RECEIVED = "asap.request.received"
+EVENT_PROCESSED = "asap.request.processed"
+
+
+@dataclass(frozen=True)
+class TraceHop:
+    """A single hop in a trace: sender -> recipient with optional duration."""
+
+    sender: str
+    recipient: str
+    duration_ms: float | None
+
+    def format_hop(self, short_urns: bool = True) -> str:
+        """Format this hop for ASCII diagram (e.g. 'A -> B (15ms)')."""
+        s = _shorten_urn(self.sender) if short_urns else self.sender
+        r = _shorten_urn(self.recipient) if short_urns else self.recipient
+        if self.duration_ms is not None:
+            return f"{s} -> {r} ({self.duration_ms:.0f}ms)"
+        return f"{s} -> {r} (?)"
+
+
+def _shorten_urn(urn: str) -> str:
+    """Shorten URN to last segment for compact display (e.g. urn:asap:agent:foo -> foo)."""
+    if ":" in urn:
+        return urn.split(":")[-1]
+    return urn
+
+
+def parse_log_line(line: str) -> dict[str, object] | None:
+    """Parse a single JSON log line.
+
+    Args:
+        line: One line of log output (e.g. structlog JSON).
+
+    Returns:
+        Parsed dict or None if not valid JSON.
+    """
+    line = line.strip()
+    if not line:
+        return None
+    try:
+        data = json.loads(line)
+        return data if isinstance(data, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+def filter_records_by_trace_id(lines: Iterable[str], trace_id: str) -> list[dict[str, object]]:
+    """Filter and parse log lines that contain the given trace_id.
+
+    Only lines that are valid JSON and contain trace_id (string match) are returned.
+    This avoids parsing every line as JSON when scanning large files.
+
+    Args:
+        lines: Log lines (e.g. from a file or stdin).
+        trace_id: Trace ID to search for.
+
+    Returns:
+        List of parsed log records that mention this trace_id.
+    """
+    trace_id_str = str(trace_id)
+    records: list[dict[str, object]] = []
+    for line in lines:
+        if trace_id_str not in line:
+            continue
+        parsed = parse_log_line(line)
+        if parsed is None:
+            continue
+        if parsed.get("trace_id") != trace_id_str:
+            continue
+        records.append(parsed)
+    return records
+
+
+def build_hops(records: list[dict[str, object]]) -> list[TraceHop]:
+    """Build ordered list of trace hops from received/processed log records.
+
+    Pairs asap.request.received with asap.request.processed by envelope_id to
+    attach duration_ms to each hop. Sorts by received timestamp when available.
+
+    Args:
+        records: Parsed log records (from filter_records_by_trace_id).
+
+    Returns:
+        Ordered list of TraceHop (sender -> recipient, duration_ms or None).
+    """
+    received_by_envelope: dict[str, dict[str, object]] = {}
+    processed_by_envelope: dict[str, dict[str, object]] = {}
+
+    for r in records:
+        event = r.get("event")
+        envelope_id = r.get("envelope_id")
+        if not isinstance(envelope_id, str):
+            continue
+        if event == EVENT_RECEIVED:
+            received_by_envelope[envelope_id] = r
+        elif event == EVENT_PROCESSED:
+            processed_by_envelope[envelope_id] = r
+
+    hops_with_meta: list[tuple[float, str, str, float | None]] = []
+
+    for envelope_id, rec in received_by_envelope.items():
+        sender = rec.get("sender")
+        recipient = rec.get("recipient")
+        if not isinstance(sender, str) or not isinstance(recipient, str):
+            continue
+        proc = processed_by_envelope.get(envelope_id)
+        duration_ms: float | None = None
+        if isinstance(proc, dict) and "duration_ms" in proc:
+            d = proc["duration_ms"]
+            if isinstance(d, (int, float)):
+                duration_ms = float(d)
+        ts = rec.get("timestamp")
+        sort_key = _timestamp_to_sort_key(ts) if isinstance(ts, str) else 0.0
+        hops_with_meta.append((sort_key, sender, recipient, duration_ms))
+
+    hops_with_meta.sort(key=lambda x: x[0])
+
+    return [TraceHop(sender=s, recipient=r, duration_ms=d) for (_, s, r, d) in hops_with_meta]
+
+
+def _timestamp_to_sort_key(ts: str) -> float:
+    """Convert ISO timestamp string to a sortable number (epoch-ish)."""
+    try:
+        from datetime import datetime
+
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        return dt.timestamp()
+    except (ValueError, TypeError):
+        return 0.0
+
+
+def format_ascii_diagram(hops: list[TraceHop], short_urns: bool = True) -> str:
+    """Format trace hops as a single-line ASCII diagram with timing.
+
+    Format: Agent A -> Agent B (15ms) -> Agent C (23ms)
+    Each hop shows recipient and duration; sender of first hop starts the chain.
+
+    Args:
+        hops: Ordered list of TraceHop from build_hops.
+        short_urns: If True, shorten URNs to last segment for display.
+
+    Returns:
+        Single line string for CLI output.
+    """
+    if not hops:
+        return ""
+    parts: list[str] = []
+    for hop in hops:
+        r = _shorten_urn(hop.recipient) if short_urns else hop.recipient
+        if hop.duration_ms is not None:
+            parts.append(f"{r} ({hop.duration_ms:.0f}ms)")
+        else:
+            parts.append(f"{r} (?)")
+    first_sender = _shorten_urn(hops[0].sender) if short_urns else hops[0].sender
+    return first_sender + " -> " + " -> ".join(parts)
+
+
+def extract_trace_ids(lines: Iterable[str]) -> list[str]:
+    """Extract unique trace IDs from log lines (received/processed events only).
+
+    Args:
+        lines: Log lines (e.g. from file or stdin).
+
+    Returns:
+        Sorted list of unique trace_id values found in asap.request.received
+        or asap.request.processed events.
+    """
+    seen: set[str] = set()
+    for line in lines:
+        if EVENT_RECEIVED not in line and EVENT_PROCESSED not in line:
+            continue
+        parsed = parse_log_line(line)
+        if parsed is None:
+            continue
+        if parsed.get("event") not in (EVENT_RECEIVED, EVENT_PROCESSED):
+            continue
+        tid = parsed.get("trace_id")
+        if isinstance(tid, str) and tid:
+            seen.add(tid)
+    return sorted(seen)
+
+
+def trace_to_json_export(trace_id: str, hops: list[TraceHop]) -> dict[str, object]:
+    """Build a JSON-serializable dict for a trace (for --format json and external tools).
+
+    Args:
+        trace_id: Trace ID.
+        hops: Ordered list of TraceHop from build_hops.
+
+    Returns:
+        Dict with keys: trace_id, hops (list of {sender, recipient, duration_ms}).
+    """
+    return {
+        "trace_id": trace_id,
+        "hops": [
+            {
+                "sender": h.sender,
+                "recipient": h.recipient,
+                "duration_ms": h.duration_ms,
+            }
+            for h in hops
+        ],
+    }
+
+
+def parse_trace_from_lines(lines: Iterable[str], trace_id: str) -> tuple[list[TraceHop], str]:
+    """Parse logs and build ASCII diagram for a trace_id.
+
+    Args:
+        lines: Log lines (e.g. from file or stdin).
+        trace_id: Trace ID to filter and visualize.
+
+    Returns:
+        Tuple of (list of TraceHop, ASCII diagram string). Diagram is empty
+        if no matching records.
+    """
+    records = filter_records_by_trace_id(lines, trace_id)
+    hops = build_hops(records)
+    diagram = format_ascii_diagram(hops)
+    return hops, diagram

asap/observability/trace_ui.py

@@ -0,0 +1,218 @@
+"""Optional Web UI for ASAP trace visualization.
+
+Serves a simple FastAPI app to browse traces, search by trace_id, and visualize
+request flow from pasted JSON log lines (ASAP_LOG_FORMAT=json).
+
+Run with: uvicorn asap.observability.trace_ui:app --reload
+Then open http://localhost:8000
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse
+from pydantic import BaseModel
+
+from asap.observability.trace_parser import (
+    TraceHop,
+    extract_trace_ids,
+    parse_trace_from_lines,
+)
+
+MAX_LOG_LINES_LENGTH = 2 * 1024 * 1024
+
+
+def _parse_log_lines(raw: str, max_length: int = MAX_LOG_LINES_LENGTH) -> list[str]:
+    """Parse raw log lines into non-empty stripped lines; raise 413 if over max_length."""
+    if len(raw) > max_length:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Log lines payload too large (max {max_length} bytes)",
+        )
+    return [s.strip() for s in raw.strip().splitlines() if s.strip()]
+
+
+app = FastAPI(
+    title="ASAP Trace UI",
+    description="Browse and visualize ASAP request traces from JSON log lines.",
+    version="0.1.0",
+)
+
+
+class LogLinesBody(BaseModel):
+    """Request body with newline-separated log lines."""
+
+    log_lines: str
+
+
+class VisualizeBody(BaseModel):
+    """Request body for trace visualization."""
+
+    log_lines: str
+    trace_id: str
+
+
+def _hops_to_dict(hops: list[TraceHop]) -> list[dict[str, Any]]:
+    """Convert TraceHop list to JSON-serializable dicts."""
+    return [
+        {"sender": h.sender, "recipient": h.recipient, "duration_ms": h.duration_ms} for h in hops
+    ]
+
+
+@app.get("/", response_class=HTMLResponse)
+def index() -> HTMLResponse:
+    """Serve the trace browser UI (paste logs, list trace IDs, visualize)."""
+    html = _INDEX_HTML
+    return HTMLResponse(html)
+
+
+@app.post("/api/traces/list")
+def list_traces(body: LogLinesBody) -> dict[str, Any]:
+    """Extract unique trace IDs from pasted log lines."""
+    lines = _parse_log_lines(body.log_lines)
+    trace_ids = extract_trace_ids(lines)
+    return {"trace_ids": trace_ids}
+
+
+@app.post("/api/traces/visualize")
+def visualize_trace(body: VisualizeBody) -> dict[str, Any]:
+    """Parse logs and return hops + ASCII diagram for the given trace_id."""
+    lines = _parse_log_lines(body.log_lines)
+    hops, diagram = parse_trace_from_lines(lines, body.trace_id.strip())
+    if not diagram:
+        raise HTTPException(status_code=404, detail=f"No trace found for: {body.trace_id}")
+    return {
+        "trace_id": body.trace_id,
+        "hops": _hops_to_dict(hops),
+        "diagram": diagram,
+    }
+
+
+_INDEX_HTML = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>ASAP Trace UI</title>
+  <style>
+    * { box-sizing: border-box; }
+    body { font-family: system-ui, sans-serif; max-width: 900px; margin: 1rem auto; padding: 0 1rem; }
+    h1 { font-size: 1.25rem; }
+    label { display: block; margin-top: 0.75rem; font-weight: 600; }
+    textarea { width: 100%; min-height: 120px; font-family: monospace; font-size: 0.8rem; padding: 0.5rem; }
+    input[type="text"] { width: 100%; max-width: 320px; padding: 0.4rem; }
+    button { margin-top: 0.5rem; padding: 0.4rem 0.8rem; cursor: pointer; }
+    .result { margin-top: 1rem; padding: 0.75rem; background: #f5f5f5; border-radius: 4px; white-space: pre-wrap; font-family: monospace; font-size: 0.9rem; }
+    .error { background: #fee; color: #c00; }
+    ul { margin: 0.25rem 0; padding-left: 1.25rem; }
+    ul li { cursor: pointer; margin: 0.2rem 0; }
+    ul li:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <h1>ASAP Trace UI</h1>
+  <p>Paste ASAP JSON log lines below (one event per line, <code>ASAP_LOG_FORMAT=json</code>), then list trace IDs or visualize one.</p>
+
+  <label for="logs">Log lines</label>
+  <textarea id="logs" placeholder='{"event":"asap.request.received","trace_id":"t1",...}
+{"event":"asap.request.processed","trace_id":"t1","duration_ms":15,...}'></textarea>
+
+  <button id="btnList">List trace IDs</button>
+  <div id="listResult" class="result" style="display:none;"></div>
+
+  <label for="traceId">Trace ID (or click one above)</label>
+  <input type="text" id="traceId" placeholder="e.g. trace-abc">
+
+  <button id="btnViz">Visualize</button>
+  <div id="vizResult" class="result" style="display:none;"></div>
+
+  <script>
+    function escapeHtml(s) {
+      if (typeof s !== 'string') return '';
+      const m = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+      return s.replace(/[&<>"']/g, function(c) { return m[c] || c; });
+    }
+    function errorMessage(e) {
+      return e instanceof Error ? e.message : String(e);
+    }
+    function showError(el, msg) {
+      el.textContent = 'Error: ' + msg;
+      el.classList.add('error');
+      el.style.display = 'block';
+    }
+    function renderTraceList(data, listResult, traceIdEl) {
+      if (data.trace_ids && data.trace_ids.length) {
+        const safe = data.trace_ids.map(function(t) {
+          return '<li data-trace="' + escapeHtml(t) + '">' + escapeHtml(t) + '</li>';
+        });
+        listResult.innerHTML = 'Trace IDs: <ul>' + safe.join('') + '</ul>';
+        listResult.querySelectorAll('li').forEach(function(li) {
+          li.onclick = function() { traceIdEl.value = li.dataset.trace || ''; };
+        });
+      } else {
+        listResult.textContent = 'No trace IDs found in log lines.';
+      }
+      listResult.classList.remove('error');
+      listResult.style.display = 'block';
+    }
+
+    const logsEl = document.getElementById('logs');
+    const traceIdEl = document.getElementById('traceId');
+    const listResult = document.getElementById('listResult');
+    const vizResult = document.getElementById('vizResult');
+
+    document.getElementById('btnList').onclick = async function() {
+      listResult.style.display = 'none';
+      const logLines = logsEl.value.trim();
+      if (!logLines) {
+        listResult.textContent = 'Paste log lines first.';
+        listResult.style.display = 'block';
+        return;
+      }
+      try {
+        const r = await fetch('/api/traces/list', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ log_lines: logLines }),
+        });
+        const data = await r.json();
+        renderTraceList(data, listResult, traceIdEl);
+      } catch (e) {
+        showError(listResult, errorMessage(e));
+      }
+    };
+
+    document.getElementById('btnViz').onclick = async function() {
+      vizResult.style.display = 'none';
+      const logLines = logsEl.value.trim();
+      const traceId = traceIdEl.value.trim();
+      if (!logLines || !traceId) {
+        vizResult.textContent = 'Paste log lines and enter a trace ID.';
+        vizResult.style.display = 'block';
+        return;
+      }
+      try {
+        const r = await fetch('/api/traces/visualize', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ log_lines: logLines, trace_id: traceId }),
+        });
+        if (!r.ok) {
+          const err = await r.json();
+          throw new Error(err.detail || r.statusText);
+        }
+        const data = await r.json();
+        vizResult.textContent = data.diagram || JSON.stringify(data, null, 2);
+        vizResult.classList.remove('error');
+        vizResult.style.display = 'block';
+      } catch (e) {
+        showError(vizResult, errorMessage(e));
+      }
+    };
+  </script>
+</body>
+</html>
+"""