Skip to content

TraceSpanDetail

TraceSpanDetail renders a detailed view of a single trace span. It displays the span's name, kind, status, timing, and provides collapsible sections for the full input data, output data, attributes, and events as formatted JSON.

Import

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

Props

Name Type Required Default Description
span SpanUI Yes -- The span object to display. Contains all span metadata including input, output, attributes, and events.

Features

The header section displays:

  • Span name -- the operation name (e.g., gemini.generateContent, tool.fetchTelemetry)
  • Kind badge -- colored badge indicating the span kind (llm, tool, retrieval, agent, internal)
  • Status badge -- colored badge showing the span status (ok, error, unset)
  • Duration -- formatted duration (e.g., 1.2s, 450ms)
  • Timestamps -- start and end times

Input Section

A collapsible section showing the span's input data as syntax-highlighted JSON. For LLM spans, this typically includes the prompt, system instruction, and tool declarations. For tool spans, this shows the tool arguments.

Output Section

A collapsible section showing the span's output data as syntax-highlighted JSON. For LLM spans, this includes the model response, token counts, and finish reason. For tool spans, this shows the tool result.

Attributes

A collapsible section showing the span's attributes as a key-value table. Attributes include metadata such as model name, temperature, tool name, and custom attributes.

Events

A collapsible section showing the span's events as a chronological list. Each event has a name, timestamp, and optional attributes. Events can represent milestones like "first token received" or "tool call started".

JSON Formatting

All JSON sections use syntax highlighting with collapsible nested objects. Large values are truncated with an "expand" option.

Usage

Basic Span Detail

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

const span: SpanUI = {
  spanId: "span-abc-123",
  name: "gemini.generateContent",
  kind: "llm",
  status: "ok",
  startTime: "2026-02-25T10:30:00.000Z",
  endTime: "2026-02-25T10:30:02.400Z",
  durationMs: 2400,
  input: {
    model: "gemini-2.0-flash",
    systemInstruction: "You are a helpful assistant.",
    contents: [
      { role: "user", parts: [{ text: "What is the current temperature?" }] },
    ],
  },
  output: {
    candidates: [
      {
        content: {
          role: "model",
          parts: [{ text: "The current temperature is 21.5 degrees." }],
        },
        finishReason: "STOP",
      },
    ],
    usageMetadata: {
      promptTokenCount: 45,
      candidatesTokenCount: 12,
      totalTokenCount: 57,
    },
  },
  attributes: {
    "gen_ai.system": "gemini",
    "gen_ai.request.model": "gemini-2.0-flash",
    "gen_ai.request.temperature": 0.2,
  },
};

function SpanView() {
  return <TraceSpanDetail span={span} />;
}

Inside a Trace Layout

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

function TraceWithDetail({
  trace,
  spans,
}: {
  trace: TraceUI;
  spans: SpanUI[];
}) {
  const [selectedSpan, setSelectedSpan] = useState<SpanUI | null>(null);

  return (
    <div style={{ display: "flex", gap: 16 }}>
      <div style={{ flex: 1 }}>
        <TraceTimeline
          trace={trace}
          spans={spans}
          onClose={() => {}}
        />
      </div>
      {selectedSpan && (
        <div style={{ flex: 1 }}>
          <TraceSpanDetail span={selectedSpan} />
        </div>
      )}
    </div>
  );
}

Tool Span Example

const toolSpan: SpanUI = {
  spanId: "span-tool-456",
  parentSpanId: "span-abc-123",
  name: "tool.fetchBuildingTelemetry",
  kind: "tool",
  status: "ok",
  startTime: "2026-02-25T10:30:00.500Z",
  endTime: "2026-02-25T10:30:01.300Z",
  durationMs: 800,
  input: {
    buildingId: "building-42",
    metric: "indoor_temperature",
    timeRange: "last_24h",
  },
  output: {
    dataPoints: 288,
    average: 21.5,
    min: 19.2,
    max: 23.8,
  },
  attributes: {
    "tool.name": "fetchBuildingTelemetry",
    "tool.source": "mcp",
  },
};