Skip to content

Trace Backend

createHttpTraceBackend creates a TraceBackend that communicates with the trace API via HTTP. The backend provides methods for listing traces with pagination and filtering, and fetching individual trace details with spans.

Import

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

Options

interface CreateHttpTraceBackendOptions {
  /**
   * Base URL for the trace API.
   * @default ""
   */
  baseUrl?: string;

  /**
   * Path prefix for trace endpoints.
   * @default "/api/traces"
   */
  pathPrefix?: string;

  /**
   * Function that returns headers to include in every request.
   * Called on each request to support token refresh.
   */
  getHeaders?: () => Record<string, string>;
}

Return Value

Returns a TraceBackend object:

interface TraceBackend {
  /**
   * List traces with pagination and optional filtering.
   */
  listTraces: (params: {
    page: number;
    pageSize: number;
    filter?: TraceListFilter;
  }) => Promise<{ traces: TraceUI[]; total: number }>;

  /**
   * Fetch a single trace with its spans and config snapshot.
   */
  getTrace: (traceId: string) => Promise<{
    trace: TraceUI;
    spans: SpanUI[];
    configSnapshot?: ConfigSnapshotUI;
  }>;
}

API Endpoints

The backend communicates with the following endpoints:

Method Endpoint Description
GET {pathPrefix} List traces. Query parameters: page, pageSize, agent, status, startDate, endDate, tag, search.
GET {pathPrefix}/{traceId} Get a single trace with spans and config snapshot.

List Traces Response

{
  "traces": [
    {
      "traceId": "trace-abc-123",
      "agent": "qa-chat",
      "status": "ok",
      "startTime": "2026-02-25T10:30:00.000Z",
      "endTime": "2026-02-25T10:30:05.200Z",
      "durationMs": 5200,
      "totalTokens": 1250,
      "inputTokens": 800,
      "outputTokens": 450,
      "estimatedCost": 0.0012,
      "prompt": "What is the current temperature?",
      "tags": ["production", "building-42"]
    }
  ],
  "total": 142
}

Get Trace Response

{
  "trace": { ... },
  "spans": [
    {
      "spanId": "span-001",
      "name": "agent.execute",
      "kind": "agent",
      "status": "ok",
      "startTime": "2026-02-25T10:30:00.000Z",
      "endTime": "2026-02-25T10:30:05.200Z",
      "durationMs": 5200,
      "input": { ... },
      "output": { ... }
    }
  ],
  "configSnapshot": { ... }
}

Usage

Basic Trace Backend

import {
  createHttpTraceBackend,
  TraceExplorer,
} 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}
    />
  );
}

Custom Path Prefix

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

Direct API Usage

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

// List traces
const { traces, total } = await traceBackend.listTraces({
  page: 0,
  pageSize: 10,
  filter: { status: "error", agent: "incident-resolver" },
});

// Get trace detail
const { trace, spans, configSnapshot } = await traceBackend.getTrace(
  "trace-abc-123"
);

With useTraceExplorer Hook

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

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

function CustomTraceView() {
  const { traces, total, page, setPage, isLoading } = useTraceExplorer({
    backend: traceBackend,
    pageSize: 20,
  });

  // Custom rendering...
}