Skip to content

TraceExplorer

TraceExplorer renders a paginated, filterable table of agent execution traces. Each row summarizes a trace with columns for timestamp, agent name, status, duration, token usage, cost, prompt preview, and tags. Clicking a row expands it to show a TraceTimeline waterfall view.

Import

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

Props

Name Type Required Default Description
backend TraceBackend Yes -- Backend instance created by createHttpTraceBackend. Provides methods for listing traces and fetching trace details.
pageSize number No 25 Number of traces per page.
initialFilter TraceListFilter No {} Initial filter applied when the component mounts.
refreshInterval number No -- Auto-refresh interval in milliseconds. When set, the trace list refreshes automatically at this interval. Set to 0 or undefined to disable.
columns TraceColumn[] No See default columns Array of column definitions controlling which columns are displayed and in what order.
style React.CSSProperties No -- Custom inline styles applied to the root container.

Default Columns

When the columns prop is not provided, the following columns are rendered:

Column Key Header Description
time Time Trace start timestamp, formatted as relative time
agent Agent Agent name from the trace metadata
status Status Color-coded status badge (ok, error, timeout)
duration Duration Total trace duration (e.g., 2.4s)
tokens Tokens Total token count (input + output)
cost Cost Estimated cost in USD
prompt Prompt Truncated user prompt preview
tags Tags Trace tags as small badges

TraceColumn Type

interface TraceColumn {
  /** Unique column key */
  key: string;

  /** Column header text */
  header: string;

  /** Column width (CSS value) */
  width?: string;

  /**
   * Custom render function for cell content.
   * Receives the TraceUI object for the row.
   */
  render?: (trace: TraceUI) => React.ReactNode;
}

TraceListFilter Type

interface TraceListFilter {
  /** Filter by agent name (exact match) */
  agent?: string;

  /** Filter by trace status */
  status?: TraceStatus;

  /** Filter traces after this date */
  startDate?: Date;

  /** Filter traces before this date */
  endDate?: Date;

  /** Filter by tag (traces must contain this tag) */
  tag?: string;

  /** Free-text search across prompt content */
  search?: string;
}

Features

Filtering

A filter bar above the table provides:

  • Agent selector -- dropdown of agent names observed in traces
  • Status filter -- filter by ok, error, or timeout
  • Date range -- start and end date pickers
  • Tag filter -- filter by a specific tag
  • Search -- free-text search across prompt content

Pagination

Navigation controls at the bottom show the current page, total traces, and page forward/backward buttons. The pageSize prop controls how many traces appear per page.

Auto-Refresh

When refreshInterval is set, the component periodically re-fetches the trace list. A small indicator shows when the next refresh will occur. The timer resets when the user manually interacts with filters or pagination.

Row Expansion

Clicking a trace row expands it inline to show a TraceTimeline waterfall view of the trace's spans. Only one row can be expanded at a time.

Custom Columns

Override the default columns by passing a columns array. Each column can define a custom render function for full control over cell content.

Usage

Basic Trace Explorer

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

const traceBackend = createHttpTraceBackend({
  baseUrl: "https://api.example.com",
  getHeaders: () => ({
    Authorization: `Bearer ${getToken()}`,
  }),
});

function TracesPage() {
  return (
    <TraceExplorer
      backend={traceBackend}
      pageSize={25}
      refreshInterval={30000}
    />
  );
}

With Initial Filter

function FilteredTraces() {
  return (
    <TraceExplorer
      backend={traceBackend}
      initialFilter={{
        agent: "incident-resolver",
        status: "error",
        startDate: new Date("2026-01-01"),
      }}
      pageSize={50}
    />
  );
}

Custom Columns

import { TraceExplorer, TraceColumn, TraceUI } from "@modernpath/agent-ui-react";

const columns: TraceColumn[] = [
  { key: "time", header: "Timestamp" },
  { key: "agent", header: "Agent" },
  { key: "status", header: "Status" },
  { key: "duration", header: "Duration" },
  {
    key: "user",
    header: "User",
    render: (trace: TraceUI) => (
      <span>{trace.metadata?.userId ?? "N/A"}</span>
    ),
  },
  { key: "prompt", header: "Prompt", width: "40%" },
];

function CustomTraces() {
  return (
    <TraceExplorer
      backend={traceBackend}
      columns={columns}
      pageSize={20}
    />
  );
}

Full-Page Layout

function FullPageTraces() {
  return (
    <TraceExplorer
      backend={traceBackend}
      pageSize={50}
      refreshInterval={15000}
      style={{
        height: "100vh",
        padding: 24,
      }}
    />
  );
}