Implementation:Truera Trulens Record Viewer Utils

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

Overview

utils.ts is the core utility module that provides call-stack tree construction from raw JSON data, node map generation, and time formatting functions for the TruLens record viewer.

Description

This module contains seven exported utility functions and one internal helper function that together form the data processing pipeline for transforming raw record JSON into the tree structures consumed by the record viewer UI components.

Tree Construction Functions:

getClassNameFromCell(stackCell) -- Extracts the class name from a stack cell by reading stackCell.method.obj.cls.name.

getMethodNameFromCell(stackCell) -- Extracts the method name from a stack cell by reading stackCell.method.name.

getPathName(stackCell) -- Resolves the path from a stack cell. Handles two serialization formats: if the path is a plain string (new format), it returns it directly. For the old structured format, it iterates over the path array, converting item_or_attribute entries to dot-notation and index entries to bracket-notation, filtering out unsupported path component types.

addCallToTree(tree, call, stack, index) (internal) -- Recursively inserts a single call into the tree. At each level, it searches for an existing child node matching the class name and whose time range encompasses the call. If at the top of the stack (leaf level) and a match exists, it updates the match's timing and raw data; if no match exists, it creates a new leaf StackTreeNode. For intermediate stack levels, it either finds a matching intermediate node or creates a new one, then recurses to the next stack level.

createTreeFromCalls(recordJSON, appName) -- The primary tree-building entry point. Creates a root StackTreeNode with the given app name and record-level performance timing, then iterates over all calls in the record, invoking addCallToTree for each one. Returns the fully constructed root node.

createNodeMap(node) -- Performs a breadth-first traversal of the tree starting from the given node and produces a flat Record<string, StackTreeNode> dictionary keyed by each node's nodeId. This enables O(1) lookups by the UI components.

Tree UI Helpers:

getDefaultExpandedItems(node, maxDepth) -- Performs a depth-first traversal collecting node IDs up to the specified depth limit, returning an array of strings suitable for initializing a tree view's expanded state.

Time Formatting Functions:

formatTime(timestampInMicroSeconds) -- Converts a microsecond-precision timestamp into a human-readable string in the format M/D/YYYY HH:MM:SS.µµµµµµ. Divides by 1000 to get a JavaScript Date, then appends the remaining microseconds zero-padded to 6 digits.

formatDuration(durationInMicroSeconds) -- Converts a duration in microseconds to a human-readable string with appropriate units: microseconds (us) for values under 1000, milliseconds (ms) for values under 1,000,000, and seconds (s) for larger values.

getMicroseconds(timestamp) -- Parses a Python datetime ISO string into microseconds since epoch. Converts via JavaScript Date (millisecond precision), multiplies by 1000, then extracts any additional sub-millisecond digits from the fractional seconds portion of the original string.

Usage

Use these utilities to transform raw RecordJSONRaw data into a StackTreeNode tree, build a lookup map for the UI, and format timing values for display. These functions are called during the initialization phase of the record viewer component.

Code Reference

Source Location

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

Signature

export const getClassNameFromCell = (stackCell: StackJSONRaw): string;

export const getMethodNameFromCell = (stackCell: StackJSONRaw): string;

export const getPathName = (stackCell: StackJSONRaw): string;

// Internal (not exported):
// const addCallToTree = (tree: StackTreeNode, call: CallJSONRaw, stack: StackJSONRaw[], index: number): void;

export const createTreeFromCalls = (recordJSON: RecordJSONRaw, appName: string): StackTreeNode;

export const createNodeMap = (node: StackTreeNode): Record<string, StackTreeNode>;

export const getDefaultExpandedItems = (node: StackTreeNode, maxDepth: number): string[];

export const formatTime = (timestampInMicroSeconds: number): string;

export const formatDuration = (durationInMicroSeconds: number): string;

export const getMicroseconds = (timestamp: string): number;

Import

import {
  getClassNameFromCell,
  getMethodNameFromCell,
  getPathName,
  createTreeFromCalls,
  createNodeMap,
  getDefaultExpandedItems,
  formatTime,
  formatDuration,
  getMicroseconds,
} from '@/utils/utils';

I/O Contract

Inputs

Name	Type	Required	Description
stackCell	StackJSONRaw	yes	A single call stack cell used by getClassNameFromCell, getMethodNameFromCell, and getPathName.
recordJSON	RecordJSONRaw	yes	The full record JSON object used by createTreeFromCalls to iterate over calls and extract performance data.
appName	string	yes	The application display name used as the root node's name in createTreeFromCalls.
node	StackTreeNode	yes	A tree node used as the starting point for createNodeMap and getDefaultExpandedItems.
maxDepth	number	yes	The maximum tree depth for getDefaultExpandedItems to expand.
timestampInMicroSeconds	number	yes	A microsecond-precision timestamp for formatTime.
durationInMicroSeconds	number	yes	A duration in microseconds for formatDuration.
timestamp	string	yes	A Python datetime ISO string for getMicroseconds.

Outputs

Name	Type	Description
getClassNameFromCell	string	The class name extracted from the stack cell's method object.
getMethodNameFromCell	string	The method name extracted from the stack cell's method descriptor.
getPathName	string	The resolved path string from the stack cell, supporting both new string and old structured formats.
createTreeFromCalls	StackTreeNode	The root node of the fully constructed call stack tree.
createNodeMap	Record<string, StackTreeNode>	A flat dictionary mapping node IDs to StackTreeNode instances.
getDefaultExpandedItems	string[]	An array of node IDs representing nodes that should be expanded by default up to maxDepth.
formatTime	string	A human-readable timestamp string in the format "M/D/YYYY HH:MM:SS.µµµµµµ", or empty string if input is falsy.
formatDuration	string	A human-readable duration string with appropriate units (us, ms, or s), or empty string if input is null/undefined.
getMicroseconds	number	The number of microseconds since Unix epoch, or 0 if the input is falsy.

Usage Examples

import { createTreeFromCalls, createNodeMap, getDefaultExpandedItems } from '@/utils/utils';
import { RecordJSONRaw } from '@/utils/types';

// Build a call stack tree from a record
const recordJSON: RecordJSONRaw = fetchedData.record_json;
const appName = fetchedData.app_json.root_class.name;
const root = createTreeFromCalls(recordJSON, appName);

// Create a flat lookup map for O(1) node access
const nodeMap = createNodeMap(root);

// Get default expanded items for tree view (expand 3 levels deep)
const expandedIds = getDefaultExpandedItems(root, 3);

// Format timing values for display
import { formatTime, formatDuration } from '@/utils/utils';

const startLabel = formatTime(root.startTime);   // e.g. "1/1/2024 00:00:00.000000"
const durationLabel = formatDuration(root.timeTaken); // e.g. "1500 ms"

// Extract info from a stack cell
import { getClassNameFromCell, getMethodNameFromCell, getPathName } from '@/utils/utils';

const call = recordJSON.calls[0];
const topCell = call.stack[call.stack.length - 1];
console.log(getClassNameFromCell(topCell));   // e.g. "ChatOpenAI"
console.log(getMethodNameFromCell(topCell));  // e.g. "invoke"
console.log(getPathName(topCell));            // e.g. ".app.llm"

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment