Principle:Truera Trulens Record Trace Tree Visualization

Knowledge Sources	Truera_Trulens TruLens Docs
Domains	Trace Visualization, OTEL Observability, Tree Data Structures, Dashboard UI
Last Updated	2026-02-14 08:00 GMT

Overview

Hierarchical trace visualization is the principle of converting flat, sequential call records or OpenTelemetry (OTEL) spans into parent-child tree structures, then rendering those trees as interactive UI components with tree views, timeline views, and detail panels for exploring LLM application execution.

Description

When an LLM application executes through TruLens, every function call, retrieval operation, generation step, and tool invocation is recorded as either a legacy call record (with a stack-based path hierarchy) or an OTEL span (with explicit trace_id, span_id, and parent_id fields). These records arrive as flat lists -- there is no inherent tree structure in the raw data. The challenge is to reconstruct the execution hierarchy so users can visually understand which operations are nested within others, how long each took, and what data flowed through each step.

The Record Trace Tree Visualization principle addresses this by defining:

1. A canonical tree node representation (StackTreeNode) that holds a span's name, timing information, parent-child relationships, and either raw call data (legacy) or OTEL attributes. Two variants exist: a legacy StackTreeNode that derives hierarchy from call stack path analysis, and an OTEL StackTreeNode that uses explicit span_id/parent_id linkage.

2. A tree construction algorithm that maps flat span lists into a rooted tree. For OTEL spans, this involves building a node map keyed by span_id, grouping children by parent_id, identifying the root node (of type record_root), recursively attaching children sorted by start timestamp, and handling orphaned nodes (spans whose parent is not in the current set) by placing them under a special container node.

3. A dual-view rendering model where the same tree can be displayed as either an interactive collapsible tree (RecordTree) or a flat timeline table (RecordTable). Both views support node selection, which updates a detail panel showing the selected node's attributes, inputs/outputs, or raw JSON.

4. Evaluation span filtering -- spans of type EVAL and EVAL_ROOT are excluded from the trace tree because they represent feedback evaluations rather than application execution. This keeps the trace view focused on the application's own call hierarchy.

In the ML observability landscape, this principle is the bridge between raw telemetry data and human-interpretable execution exploration. It is analogous to distributed tracing flame graphs in systems like Jaeger or Zipkin, but specialized for LLM application workflows where the semantic span types (retrieval, generation, reranking, embedding, tool invocation, agent invocation) carry domain-specific meaning.

Usage

This pattern is appropriate when:

The system captures nested execution traces where operations are logically contained within other operations (e.g., a retrieval step inside a RAG pipeline, an LLM call inside a tool invocation).
Trace data arrives as a flat list of spans with parent-child identifiers rather than a pre-built tree, requiring reconstruction.
Users need to interactively explore execution details at multiple levels of granularity -- from a high-level overview of the entire record down to the specific arguments and return values of individual function calls.
The system must support both legacy and modern telemetry formats (pre-OTEL call stacks and OTEL spans) with a unified visualization experience.
Orphaned spans (those whose parent is missing from the current dataset) must be handled gracefully rather than silently dropped.

Theoretical Basis

The tree construction algorithm operates in the following abstract phases:

Phase 1: Span Filtering

Given a flat list of spans, remove all evaluation-related spans (those with span_type of EVAL or EVAL_ROOT). These represent feedback evaluation executions, not application traces, and are displayed separately in the feedback results panel.

Phase 2: Node Construction

For each remaining span, create a tree node containing:

name -- the span or method name
id -- the unique span identifier
parentId -- the identifier of the parent span
startTime and endTime -- timestamps for duration computation
attributes -- the full set of span attributes (for OTEL) or raw call data (for legacy)

Phase 3: Index Construction

Build two lookup structures:

A nodeMap mapping each node's id to the node itself, enabling O(1) lookups.
A childrenMap mapping each parent_id to the list of child nodes, enabling efficient tree assembly.

Phase 4: Root Identification

Identify the root node by finding the span whose span_type attribute equals record_root. The algorithm requires exactly one root node; zero or multiple root nodes are treated as errors.

Phase 5: Recursive Tree Assembly

Starting from the root node, recursively assign children from the childrenMap. Children within each parent are sorted by startTime to reflect chronological execution order.

 FUNCTION buildTree(node, childrenMap):
     children = childrenMap[node.id] sorted by startTime
     node.children = children
     FOR EACH child IN children:
         buildTree(child, childrenMap)

Phase 6: Orphan Handling

After tree assembly, collect all node IDs reachable from the root. Any nodes not in this reachable set whose parentId is also absent from the nodeMap are considered orphaned root candidates. Each orphaned root has its own subtree built recursively, then all orphaned subtrees are attached to a synthetic "Orphaned nodes" container appended as a child of the root. This ensures no span data is silently lost.

Phase 7: Dual-View Rendering

The constructed tree is rendered through two complementary views:

Tree View -- A recursive, collapsible list where each node can be expanded to reveal its children. Selection of a node updates the detail panel on the right side of the interface.
Timeline View -- A flat table representation showing all nodes with their timing as horizontal bars, providing a temporal overview of the execution. This is analogous to a Gantt chart or flame graph.

Both views share the same underlying tree data structure and selection state, allowing users to switch between structural and temporal perspectives without losing context.

Phase 8: Detail Rendering

When a node is selected, the detail panel offers multiple sub-tabs:

Details -- Structured display of the node's semantic attributes (input messages, output messages, model name, cost, tokens, retrieved contexts, etc.), organized by span type.
Raw Attributes -- A JSON viewer showing the complete, unprocessed attribute map for debugging and advanced inspection.
Record Information -- A summary panel showing top-level record metadata (total duration, app name, app version).

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment