Skip to content

TraceTimeline

TraceTimeline renders a waterfall timeline of all spans within a single trace. Each span is displayed as a horizontal bar positioned according to its start time and duration, with nesting to show parent-child relationships. Clicking a span opens the TraceSpanDetail view.

Import

import { TraceTimeline } from "@modernpath/agent-ui-react";

Props

Name Type Required Default Description
trace TraceUI Yes -- The trace object containing metadata such as traceId, agent name, status, and timestamps.
spans SpanUI[] Yes -- Array of span objects belonging to this trace. Each span includes timing, status, kind, and optional parent reference.
configSnapshot ConfigSnapshotUI No -- Optional configuration snapshot captured at the time of the trace. Displayed in a collapsible panel.
onClose () => void No -- Callback invoked when the user clicks the close button. Use this to navigate back to the trace list.

TraceUI Type

interface TraceUI {
  traceId: string;
  agent: string;
  status: TraceStatus;
  startTime: string;
  endTime?: string;
  durationMs: number;
  totalTokens?: number;
  inputTokens?: number;
  outputTokens?: number;
  estimatedCost?: number;
  prompt?: string;
  tags?: string[];
  metadata?: Record<string, unknown>;
}

SpanUI Type

interface SpanUI {
  spanId: string;
  parentSpanId?: string;
  name: string;
  kind: SpanKind;
  status: SpanStatus;
  startTime: string;
  endTime?: string;
  durationMs: number;
  input?: unknown;
  output?: unknown;
  attributes?: Record<string, unknown>;
  events?: Array<{
    name: string;
    timestamp: string;
    attributes?: Record<string, unknown>;
  }>;
}

Features

Waterfall Visualization

Spans are rendered as horizontal bars on a time axis:

  • The bar width represents the span duration relative to the total trace duration.
  • The bar position represents the span's start time relative to the trace start.
  • Nested spans are indented to show parent-child relationships.

Span Kind Icons

Each span displays an icon based on its kind:

Kind Icon Description
llm Brain icon LLM call to Gemini or other model
tool Wrench icon Tool invocation
retrieval Search icon Knowledge base retrieval
agent Robot icon Sub-agent delegation
internal Gear icon Internal processing step

Status Colors

Status Color
ok Green
error Red
unset Gray

Config Snapshot

When configSnapshot is provided, a collapsible "Configuration" panel shows the agent configuration (model, temperature, tools, prompts) that was active when the trace was recorded.

Span Selection

Clicking a span bar opens the TraceSpanDetail view inline, showing the full input/output JSON for that span.

Usage

Basic Timeline

import {
  TraceTimeline,
  useTraceDetail,
  createHttpTraceBackend,
} from "@modernpath/agent-ui-react";

const traceBackend = createHttpTraceBackend({ baseUrl: "/api" });

function TraceView({ traceId }: { traceId: string }) {
  const { trace, spans, configSnapshot, isLoading } = useTraceDetail({
    backend: traceBackend,
    traceId,
  });

  if (isLoading || !trace) return <div>Loading...</div>;

  return (
    <TraceTimeline
      trace={trace}
      spans={spans}
      configSnapshot={configSnapshot}
      onClose={() => window.history.back()}
    />
  );
}

Embedded in a Page Layout

import { TraceTimeline, TraceUI, SpanUI } from "@modernpath/agent-ui-react";

function TraceDetailPage({
  trace,
  spans,
}: {
  trace: TraceUI;
  spans: SpanUI[];
}) {
  return (
    <div style={{ padding: 24 }}>
      <h1>Trace: {trace.traceId}</h1>
      <p>Agent: {trace.agent} | Status: {trace.status}</p>
      <TraceTimeline
        trace={trace}
        spans={spans}
        onClose={() => window.history.back()}
      />
    </div>
  );
}

With Navigation

import { useNavigate, useParams } from "react-router-dom";
import { TraceTimeline, useTraceDetail } from "@modernpath/agent-ui-react";

function TraceRoute() {
  const { traceId } = useParams<{ traceId: string }>();
  const navigate = useNavigate();
  const { trace, spans, configSnapshot, isLoading } = useTraceDetail({
    backend: traceBackend,
    traceId: traceId!,
  });

  if (isLoading || !trace) return <div>Loading trace...</div>;

  return (
    <TraceTimeline
      trace={trace}
      spans={spans}
      configSnapshot={configSnapshot}
      onClose={() => navigate("/traces")}
    />
  );
}