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

asap/observability/dashboards/asap-detailed.json

@@ -0,0 +1,131 @@
+{
+  "annotations": { "list": [] },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "liveNow": false,
+  "panels": [
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Handler executions per second by payload type (activity view)",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "normal" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
+      "id": 10,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_handler_executions_total[1m])) by (payload_type)",
+          "legendFormat": "{{payload_type}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Handler executions (by payload type)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Task state machine transition rate by from_state and to_state",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "id": 11,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_state_transitions_total[1m])) by (from_status, to_status)",
+          "legendFormat": "{{from_status}} → {{to_status}}",
+          "refId": "A"
+        }
+      ],
+      "title": "State transitions",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Circuit breaker open state (1 = open). Requires asap_circuit_breaker_open metric from client.",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "thresholds" },
+          "mappings": [
+            { "options": { "0": { "color": "green", "index": 0, "text": "closed" } }, "type": "value" },
+            { "options": { "1": { "color": "red", "index": 0, "text": "open" } }, "type": "value" }
+          ],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "red", "value": 1 }
+            ]
+          },
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
+      "id": 12,
+      "options": { "colorMode": "value", "graphMode": "none", "justifyMode": "auto", "orientation": "auto", "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false }, "textMode": "auto" },
+      "targets": [
+        {
+          "expr": "asap_circuit_breaker_open",
+          "legendFormat": "{{instance}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Circuit breaker status",
+      "type": "stat"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "State transition rate as table (from_state, to_state, rate)",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "align": "auto", "cellOptions": { "type": "auto" }, "inspect": false },
+          "mappings": [],
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 },
+      "id": 13,
+      "options": { "cellHeight": "sm", "footer": { "countRows": false, "fields": "", "reducer": ["sum"], "show": false }, "showHeader": true, "sortBy": [] },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_state_transitions_total[1m])) by (from_status, to_status)",
+          "format": "table",
+          "instant": true,
+          "refId": "A"
+        }
+      ],
+      "title": "State transitions (table)",
+      "type": "table"
+    }
+  ],
+  "refresh": "10s",
+  "schemaVersion": 38,
+  "style": "dark",
+  "tags": ["asap", "detailed", "state-machine"],
+  "templating": { "list": [] },
+  "time": { "from": "now-1h", "to": "now" },
+  "timepicker": {},
+  "timezone": "utc",
+  "title": "ASAP Detailed (topology & state)",
+  "uid": "asap-detailed",
+  "version": 1,
+  "weekStart": ""
+}

asap/observability/dashboards/asap-red.json

@@ -0,0 +1,129 @@
+{
+  "annotations": { "list": [] },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "liveNow": false,
+  "panels": [
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Requests per second by payload type",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
+      "id": 1,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_requests_total[1m])) by (payload_type)",
+          "legendFormat": "{{payload_type}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Request Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Error rate: errors / total requests",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "thresholds" },
+          "mappings": [],
+          "max": 1,
+          "min": 0,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "yellow", "value": 0.01 },
+              { "color": "red", "value": 0.05 }
+            ]
+          },
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "id": 2,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_requests_error_total[1m])) / (sum(rate(asap_requests_total[1m])) + 1e-9)",
+          "legendFormat": "Error rate",
+          "refId": "A"
+        }
+      ],
+      "title": "Error Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "95th percentile request duration",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
+      "id": 3,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.95, sum(rate(asap_request_duration_seconds_bucket[1m])) by (le))",
+          "legendFormat": "p95",
+          "refId": "A"
+        }
+      ],
+      "title": "Latency (p95)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "99th percentile request duration",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 },
+      "id": 4,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.99, sum(rate(asap_request_duration_seconds_bucket[1m])) by (le))",
+          "legendFormat": "p99",
+          "refId": "A"
+        }
+      ],
+      "title": "Latency (p99)",
+      "type": "timeseries"
+    }
+  ],
+  "refresh": "10s",
+  "schemaVersion": 38,
+  "style": "dark",
+  "tags": ["asap", "red"],
+  "templating": { "list": [] },
+  "time": { "from": "now-1h", "to": "now" },
+  "timepicker": {},
+  "timezone": "utc",
+  "title": "ASAP RED",
+  "uid": "asap-red",
+  "version": 1,
+  "weekStart": ""
+}

asap/observability/logging.py

@@ -13,6 +13,8 @@ Environment Variables:
     ASAP_LOG_FORMAT: Set to "json" for JSON output, "console" for colored output
     ASAP_LOG_LEVEL: Set log level (DEBUG, INFO, WARNING, ERROR)
     ASAP_SERVICE_NAME: Service name to include in logs
+    ASAP_DEBUG: Set to "true" or "1" to log full data and stack traces; otherwise sensitive fields are redacted
+    ASAP_DEBUG_LOG: Set to "true" or "1" to log full request/response bodies (structured JSON); for development
 
 Example:
     >>> from asap.observability.logging import get_logger, configure_logging
@@ -42,11 +44,90 @@ DEFAULT_SERVICE_NAME = "asap-protocol"
 ENV_LOG_FORMAT = "ASAP_LOG_FORMAT"
 ENV_LOG_LEVEL = "ASAP_LOG_LEVEL"
 ENV_SERVICE_NAME = "ASAP_SERVICE_NAME"
+ENV_DEBUG = "ASAP_DEBUG"
+ENV_DEBUG_LOG = "ASAP_DEBUG_LOG"
+
+# Placeholder for redacted sensitive values in logs
+REDACTED_PLACEHOLDER = "***REDACTED***"
+
+# Key substrings (case-insensitive) that indicate sensitive data to redact
+_SENSITIVE_KEY_PATTERNS = frozenset(
+    {
+        "password",
+        "token",
+        "secret",
+        "key",
+        "authorization",
+        "auth",
+        "credential",
+        "api_key",
+        "apikey",
+        "access_token",
+        "refresh_token",
+    }
+)
 
 # Module-level flag to track if logging has been configured
 _logging_configured = False
 
 
+def _is_sensitive_key(key: str) -> bool:
+    """Return True if the key name indicates sensitive data that should be redacted."""
+    lower = key.lower()
+    return any(pattern in lower for pattern in _SENSITIVE_KEY_PATTERNS)
+
+
+def sanitize_for_logging(data: dict[str, Any]) -> dict[str, Any]:
+    """Sanitize a dict for safe logging by redacting sensitive field values.
+
+    Keys matching (case-insensitive) password, token, secret, key, authorization,
+    auth, credential, api_key, apikey, access_token, refresh_token have their
+    values replaced with REDACTED_PLACEHOLDER. Handles nested
+    dicts and lists of dicts recursively. Non-sensitive keys and correlation_id
+    are preserved for debugging.
+
+    Args:
+        data: The dict to sanitize (e.g. envelope payload or request params).
+
+    Returns:
+        A new dict with sensitive values replaced; nested structures are deep-copied
+        and sanitized. Non-dict/non-list values for sensitive keys are redacted.
+
+    Example:
+        >>> sanitize_for_logging({"user": "alice", "password": "secret123"})
+        {'user': 'alice', 'password': '***REDACTED***'}
+        >>> sanitize_for_logging({"nested": {"token": "sk_live_abc"}})
+        {'nested': {'token': '***REDACTED***'}}
+    """
+    if not data:
+        return {}
+    result: dict[str, Any] = {}
+    for k, v in data.items():
+        if _is_sensitive_key(k):
+            result[k] = REDACTED_PLACEHOLDER
+        elif isinstance(v, dict):
+            result[k] = sanitize_for_logging(v)
+        elif isinstance(v, list):
+            result[k] = [
+                sanitize_for_logging(item) if isinstance(item, dict) else item for item in v
+            ]
+        else:
+            result[k] = v
+    return result
+
+
+def is_debug_mode() -> bool:
+    """Return True if ASAP_DEBUG is set to a truthy value (e.g. true, 1)."""
+    value = os.environ.get(ENV_DEBUG, "").strip().lower()
+    return value in ("true", "1", "yes", "on")
+
+
+def is_debug_log_mode() -> bool:
+    """Return True if ASAP_DEBUG_LOG is set to a truthy value (log full request/response)."""
+    value = os.environ.get(ENV_DEBUG_LOG, "").strip().lower()
+    return value in ("true", "1", "yes", "on")
+
+
 def _get_log_level() -> str:
     """Get log level from environment or use default."""
     return os.environ.get(ENV_LOG_LEVEL, DEFAULT_LOG_LEVEL).upper()
@@ -185,7 +266,6 @@ def get_logger(name: str) -> structlog.stdlib.BoundLogger:
         >>> logger = logger.bind(trace_id="trace_123")
         >>> logger.info("request.processed")  # trace_id automatically included
     """
-    # Ensure logging is configured
     if not _logging_configured:
         configure_logging()
 

asap/observability/metrics.py

@@ -150,16 +150,30 @@ class MetricsCollector:
         >>> print(collector.export_prometheus())
     """
 
-    # Default metric definitions
+    # Default metric definitions (20+ for observability)
     DEFAULT_COUNTERS: ClassVar[dict[str, str]] = {
         "asap_requests_total": "Total number of ASAP requests received",
         "asap_requests_success_total": "Total number of successful ASAP requests",
         "asap_requests_error_total": "Total number of failed ASAP requests",
         "asap_thread_pool_exhausted_total": "Total number of thread pool exhaustion events",
+        "asap_handler_executions_total": "Total number of handler executions",
+        "asap_handler_errors_total": "Total number of handler execution failures",
+        "asap_state_transitions_total": "Total number of state machine transitions",
+        "asap_transport_send_total": "Total number of transport send attempts",
+        "asap_transport_send_errors_total": "Total number of transport send errors",
+        "asap_transport_retries_total": "Total number of transport retries",
+        "asap_parse_errors_total": "Total number of JSON-RPC parse errors",
+        "asap_auth_failures_total": "Total number of authentication failures",
+        "asap_validation_errors_total": "Total number of envelope validation errors",
+        "asap_invalid_timestamp_total": "Total number of invalid timestamp rejections",
+        "asap_invalid_nonce_total": "Total number of invalid nonce rejections",
+        "asap_sender_mismatch_total": "Total number of sender identity mismatches",
     }
 
     DEFAULT_HISTOGRAMS: ClassVar[dict[str, str]] = {
         "asap_request_duration_seconds": "Request processing duration in seconds",
+        "asap_handler_duration_seconds": "Handler execution duration in seconds",
+        "asap_transport_send_duration_seconds": "Transport send duration in seconds",
     }
 
     def __init__(self) -> None:

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