Implementation:Truera Trulens StackTreeNode

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

Overview

StackTreeNode is the core data structure class that represents a single node in the hierarchical call stack tree used by the TruLens record viewer.

Description

The StackTreeNode class models one level of a recorded call stack as a tree node. Each node stores its display name, an array of child nodes, a reference to its parent nodes, timing information (start and end times in microseconds), the raw call JSON, and derived path and method name strings extracted from the stack cell.

The constructor accepts an options object with optional children, stackCell, perf, raw, and parentNodes fields plus a required name. If a perf object is provided, the constructor uses the getMicroseconds utility to convert the ISO timestamp strings into microsecond-precision numeric values. If a stackCell is provided, it extracts the path and method name using the getPathName and getMethodNameFromCell utilities.

The class exposes four computed getter properties:

timeTaken returns the duration in microseconds (endTime minus startTime).
isRoot returns true when the node has no parent nodes.
nodeId returns a unique identifier string. For root nodes this is the constant ROOT_NODE_ID (root-root-root); for other nodes it concatenates methodName, name, startTime, and endTime.
selector builds a dot-separated selector string prefixed with Select.Record, followed by the path and method name.
label returns the display label: just the name for root nodes, or name and methodName joined by a dot for non-root nodes.

Usage

Use StackTreeNode to build and traverse the call stack tree for a single TruLens record. Instances are created by the createTreeFromCalls utility function and consumed by the RecordTree, RecordTable, and Details UI components.

Code Reference

Source Location

Repository: Truera_Trulens
File: src/dashboard/react_components/record_viewer/src/utils/StackTreeNode.ts
Lines: 1-81

Signature

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

export class StackTreeNode {
  children: StackTreeNode[];
  name: string;
  path: string;
  methodName: string;
  startTime: number;
  endTime: number;
  raw?: CallJSONRaw;
  parentNodes: StackTreeNode[];

  constructor(options: {
    children?: StackTreeNode[];
    name: string;
    stackCell?: StackJSONRaw;
    raw?: CallJSONRaw;
    parentNodes?: StackTreeNode[];
    perf?: PerfJSONRaw;
  });

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

Import

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

I/O Contract

Inputs

Name	Type	Required	Description
name	string	yes	The display name of the node, typically the class name from the call stack.
children	StackTreeNode[]	no	Child nodes in the tree. Defaults to an empty array.
stackCell	StackJSONRaw	no	The raw stack cell JSON used to extract the path and method name.
raw	CallJSONRaw	no	The raw call JSON object associated with this node (present only for leaf-level calls).
parentNodes	StackTreeNode[]	no	Array of ancestor nodes from root to parent. Defaults to an empty array.
perf	PerfJSONRaw	no	Performance timing object containing start_time and end_time ISO strings.

Outputs

Name	Type	Description
StackTreeNode instance	StackTreeNode	A tree node with populated children, timing, path, methodName, and computed properties (timeTaken, isRoot, nodeId, selector, label).

Usage Examples

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

// Create a root node
const root = new StackTreeNode({
  name: 'MyApp',
  perf: { start_time: '2024-01-01T00:00:00.000000', end_time: '2024-01-01T00:00:01.500000' },
});

console.log(root.isRoot);     // true
console.log(root.nodeId);     // 'root-root-root'
console.log(root.label);      // 'MyApp'
console.log(root.timeTaken);  // 1500000 (microseconds)

// Create a child node with a stack cell
const child = new StackTreeNode({
  name: 'Retriever',
  stackCell: someStackCell,
  raw: someCallJSON,
  parentNodes: [root],
  perf: { start_time: '2024-01-01T00:00:00.200000', end_time: '2024-01-01T00:00:00.800000' },
});

root.children.push(child);
console.log(child.isRoot);    // false
console.log(child.label);     // 'Retriever.retrieve'
console.log(child.selector);  // 'Select.Record.app.retriever.retrieve'

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment