Trace Tree UI#

The Trace Tree UI renders a hierarchical, interactive view of OpenTelemetry spans within a trace. It lives in app/src/components/trace/ and is primarily surfaced on the TraceDetails page (app/src/pages/trace/TraceDetails.tsx), where it occupies the left panel of a split-panel layout alongside the SpanDetails view.

Key Components#

TraceTree (TraceTree.tsx)#

The root component. Accepts a flat spans: ISpanItem[] array, the selectedSpanNodeId string, and an optional onSpanClick callback 1. On mount it converts the flat list into a tree via createSpanTree, wraps everything in a TraceTreeProvider, and renders:

• TraceTreeToolbar — header with two toggle buttons: collapse/expand all spans, and show/hide per-span metrics (latency + token count). Collapse state is managed through TraceTreeContext; metric visibility is persisted in PreferencesContext 2.
• SpanTreeItem — recursive component that renders one span node and its children 3.

Compact mode: when the container width drops below 200px, CSS container queries zero out nesting indentation and hide edge connectors, latency text, token counts, and collapse buttons 4.

SpanTreeItem (TraceTree.tsx:224)#

Renders a single span as a clickable row inside a SpanNodeWrap. Each row shows:

• SpanKindIcon — visual indicator of span kind
• Span name (truncated with text-overflow: ellipsis)
• SpanStatusCodeIcon — shown only for ERROR status
• SpanTokenCount — shown when tokenCountTotal > 0 and metrics are enabled
• LatencyText — shown when latencyMs != null and metrics are enabled

Child spans are rendered recursively in a <ul>, with visual connectors drawn by SpanTreeEdge and SpanTreeEdgeConnector. Both connectors color themselves danger-red for ERROR-status spans 5. The selected item scrolls into view automatically via scrollIntoView 6.

A CollapseToggleButton appears on nodes that have children, allowing per-node collapse independent of the global state 7.

LatencyText (LatencyText.tsx)#

Displays span latency with color-coded severity and an optional clock icon 8:

Values are auto-scaled: under 10 ms → displayed in ms; 10 ms and above → converted to s 9. Formatting is delegated to formatFloat from numberFormatUtils.

Supporting Utilities#

createSpanTree / SpanTreeNode (utils.ts)#

createSpanTree<TSpan> converts a flat TSpan[] (constrained to ISpanItem) into SpanTreeNode<TSpan>[]. The node type is:

type SpanTreeNode<TSpan> = { span: TSpan; children: SpanTreeNode<TSpan>[] }

10

It uses a Map keyed by span ID to link children to parents via parentId, then sorts siblings by startTime.

ISpanItem / SpanStatusCodeType (types.ts)#

ISpanItem is the minimum interface any span object must satisfy to be rendered in the tree:

interface ISpanItem {
  id: string; name: string; spanKind: string;
  statusCode: SpanStatusCodeType; latencyMs: number | null;
  startTime: string; parentId: string | null; spanId: string;
  tokenCountTotal?: number | null;
  [otherKeys: string]: unknown;
}

SpanStatusCodeType is "OK" | "ERROR" | "UNSET".

numberFormatUtils.ts (numberFormatUtils.ts)#

General-purpose numeric formatting helpers built on d3-format 11:

State Management#

TraceTreeContext provides a single boolean (isCollapsed) scoped to the tree. TraceTreeProvider wraps the tree and exposes setIsCollapsed (wrapped in startTransition for non-urgent updates) 12. Individual SpanTreeItem nodes sync with this global state via a useEffect, but can also be collapsed independently 13.

Metric visibility (showMetricsInTraceTree) is persisted in the app-wide PreferencesContext, not in TraceTreeContext 14.

File Map#