Implementation:Truera Trulens Otel StackTreeNode

Knowledge Sources	Truera_Trulens
Domains	Dashboard, Observability, OpenTelemetry
Last Updated	2026-02-14 08:00 GMT

Overview

StackTreeNode is the core data structure class for the OTEL record tree, representing a single hierarchical span node with timing, attribute data, parent-child relationships, and computed properties for display.

Description

The StackTreeNode class models a single node in the span tree used by the TruLens OTEL record viewer. Each instance corresponds to one OpenTelemetry span and holds all the data needed for both hierarchical tree navigation and detail display.

Properties:

• name (string) -- The full dotted name of the span (e.g., 'my_app.pipeline.retriever').
• id (string) -- The unique span ID, used as the key in node maps and for parent-child linkage.
• parentId (string) -- The span ID of this node's parent. An empty string indicates a root-level node.
• children (StackTreeNode[]) -- An array of child nodes, populated during tree construction by createTreeFromCalls.
• startTime (number) -- The span's start timestamp (numeric, defaults to 0).
• endTime (number) -- The span's end timestamp (numeric, defaults to 0).
• attributes (SpanAttributes) -- The full OTEL attribute dictionary (Record<string, any>) associated with this span.

Computed properties (getters):

• timeTaken -- Returns endTime - startTime, representing the span duration.
• isRoot -- Returns true if parentId is falsy (empty string), indicating this is a root node.
• label -- Returns the last two segments of the dotted name (e.g., 'pipeline.retriever' from 'my_app.pipeline.retriever'), used as a compact display label in the tree view.

The module also exports a constant ROOT_NODE_ID with the value 'root-root-root', which can be used as a sentinel ID for the root node.

Usage

Use StackTreeNode whenever you need to create, manipulate, or inspect nodes in the OTEL span tree. The createTreeFromCalls function instantiates these nodes from raw Span data, and the RecordInfo component and its children consume them for rendering tree views, timelines, and detail panels.

Code Reference

Source Location

• Repository: Truera_Trulens
• File: src/dashboard/react_components/record_viewer_otel/src/types/StackTreeNode.ts
• Lines: 1-57

Signature

import { SpanAttributes } from '@/types/SpanAttributes';

export const ROOT_NODE_ID = 'root-root-root';

export class StackTreeNode {
  children: StackTreeNode[];
  name: string;
  id: string;
  startTime: number;
  endTime: number;
  attributes: SpanAttributes;
  parentId: string;

  constructor(params: {
    children?: StackTreeNode[];
    name: string;
    id: string;
    attributes: SpanAttributes;
    parentId: string;
    startTime: number;
    endTime: number;
  });

  get timeTaken(): number;
  get isRoot(): boolean;
  get label(): string;
}

Import

import { StackTreeNode, ROOT_NODE_ID } from '@/types/StackTreeNode';

I/O Contract

Inputs

Name	Type	Required	Description
children	StackTreeNode[]	no	Child nodes in the tree. Defaults to an empty array [].
name	string	yes	The full dotted name of the span (e.g., 'my_app.pipeline.retriever').
id	string	yes	The unique span ID for this node.
attributes	SpanAttributes	yes	The OTEL attribute dictionary (Record<string, any>) for this span.
parentId	string	yes	The span ID of this node's parent. Empty string for root nodes.
startTime	number	yes	The span start timestamp.
endTime	number	yes	The span end timestamp.

Outputs

Name	Type	Description
StackTreeNode instance	StackTreeNode	A fully initialized tree node with all properties set and computed getters available.

Computed Properties

Getter	Return Type	Logic	Description
timeTaken	number	this.endTime - this.startTime	The duration of the span in the same unit as the input timestamps.
isRoot	boolean	!this.parentId	Returns true when parentId is an empty string or other falsy value, indicating a root-level node.
label	string	this.name.split('.').slice(-2).join('.')	A compact display label formed from the last two dot-separated segments of the span name. For example, 'my_app.pipeline.retriever' becomes 'pipeline.retriever'.

Usage Examples

import { StackTreeNode } from '@/types/StackTreeNode';

// Create a root node
const root = new StackTreeNode({
  name: 'my_app.pipeline',
  id: 'span-root',
  parentId: '',
  startTime: 1000,
  endTime: 5000,
  attributes: { 'ai.observability.span_type': 'record_root' },
});

// Create a child node
const child = new StackTreeNode({
  name: 'my_app.pipeline.retriever',
  id: 'span-retriever',
  parentId: 'span-root',
  startTime: 1100,
  endTime: 2500,
  attributes: { 'ai.observability.span_type': 'retrieval' },
});

// Link them
root.children = [child];

// Use computed properties
console.log(root.timeTaken);  // 4000
console.log(root.isRoot);     // true
console.log(root.label);      // 'my_app.pipeline' (only one segment, so 'my_app.pipeline')
console.log(child.label);     // 'pipeline.retriever'
console.log(child.isRoot);    // false

Related Pages

• Environment:Truera_Trulens_Streamlit_Dashboard_Environment
• Truera_Trulens_Otel_CreateTreeFromCalls -- The algorithm that instantiates and links StackTreeNode objects into a tree.
• Truera_Trulens_Otel_Span_Constants -- Constants used to classify the attributes stored in each node.
• Truera_Trulens_Otel_RecordInfo_Component -- The top-level component that receives and renders the tree of StackTreeNode objects.