Trace Visualization

When auditing complex distributed systems or autonomous AI agents, reading flat log grids is extremely challenging. A single agent session might invoke dozens of tools, evaluate multiple guardrails, and hand off execution flow to other agents.

Volidator’s Trace Visualizer solves this by reconstructing flat audit logs into interactive Causality Trees (referred to internally as “Stories”). Decryption happens entirely client-side using the key in the URL hash, preserving the Zero-Knowledge security boundary.

---

Trace Visualizer Architecture

The visualization canvas compiles flat decrypted audit log entries into structured Story graphs client-side:

import { buildStoriesFromLogs } from "@volidator/dashboard";

const stories = buildStoriesFromLogs(decryptedLogs, "trace");
/*
Returns a list of structured graph stories:
[{
  id: "story_trace_88295f1c",
  title: "Trace 88295f1c",
  nodes: [
    { id: "node_1", actor: "usr_alice", action: "user.login", childCount: 3 }
  ],
  edges: [
    { id: "edge_1_2", source: "node_1", target: "node_2", type: "causality" }
  ]
}]
*/

Phase 1: Milestone Extraction (Anti-Spaghetti Collapsing)

To prevent the canvas from becoming a cluttered, unreadable “spaghetti chart”, the visualizer categorizes logs into Milestones and collapses non-milestone events under them.

• Milestone Nodes: Major events (like tool starts/errors, agent decisions, escalations, key creations/deletions, or access revokings) are rendered as distinct nodes.
• Child Event Collapsing: Minor logs (like standard read events or debug cycles) are collapsed under their nearest preceding milestone. They appear as a childCount badge on the milestone node and can be expanded inline dynamically.

A log event is classified as a milestone if it satisfies any of these criteria:

1. It is a root span (has spanId but no parentSpanId).
2. Other logs in the session point to it as a parent (parentSpanId === currentSpanId).
3. The action is high-severity (e.g., delete, revoke, deploy, export).
4. The action uses the VolidatorAgent taxonomy (e.g., decision, anomaly, refusal, handoff, tool_call).
5. The execution actor changes from the previous chronological log (e.g., transition from a User to an Agent).

---

Visualizing Relationships: Nodes & Edges

The canvas renders nodes connected by three types of Edges to demonstrate execution flow and causality:

Edge Type	Visual Style / Meaning	Trigger Condition
Causality (causality)	Direct execution flow (Parent $\to$ Child)	Mapped explicitly by the SDK using parentSpanId $\to$ spanId.
Handoff (handoff)	Delegation boundary (e.g., Agent $\leftrightarrow$ Human)	Generated when the actor type shifts between different entities.
Session (session)	Chronological spine	Links separate independent roots inside a session to maintain chronological order.

---

Semantic States and Metrics

Each node is decorated with metadata and color-coded states to allow operators to quickly assess execution health:

• 🔴 Error (error): Triggered by actions containing "error" or "denied", or when metadata.status is set to "error".
• 🟡 Warning (warning): Triggered by actions containing "warn" or "blocked", or when metadata.status is set to "warning".
• 🟢 Success (success): Triggered when metadata.status is explicitly "success".
• ⚫ Neutral (neutral): Default state for standard operations.

LLM Token and Cost Tracking

If your AI agent logs metrics (like durationMs, tokens, or cost in the metadata payload), the visualizer automatically reads and aggregates these values to display the total execution cost and latency for the entire story thread.

---

Performance Controls (Culling)

To guarantee high-performance rendering in web browsers, the visualizer implements a culling threshold:

• A story is capped at a maximum of 200 visible milestone nodes.
• If a session or trace generates more than 200 milestones, the list is truncated and the story object sets culled: true.
• A warning badge is displayed on the dashboard canvas to notify the operator that progressive disclosure has hidden extremely deep sections.

---

Auto-Title Generation

If no explicit title is provided, the visualizer dynamically generates a descriptive title for each story based on the grouping mode:

• Trace Mode: Shows Trace [first 8 chars of traceId].
• Session Mode: Shows Session [first 8 chars of sessionId].
• Target Mode: Shows Events for [target name].
• Chronological Fallback: Promotes the highest severity action (e.g., Revoke Access → database_prod).