Trace

The Trace module provides structured logging and performance tracking for agent operations, making it easier to debug, analyze, and optimize agent behavior.

Trace Classes

The module consists of two main classes:

Trace: Represents an individual trace entry with hierarchical structure
TraceDetails: Interface defining the structure of trace data

Creating a Trace

Traces can be created directly for standalone use:

import { Trace } from 'loom-agents';

const rootTrace = new Trace('main-operation', {
  input: 'user query',
  timestamp: Date.now()
});

Adding Sub-traces

Traces can be nested to represent hierarchical operations:

// Start a child trace
const parseTrace = rootTrace.start('parse-input', {
  parser: 'default',
  input_length: input.length
});

// Perform operation
const result = parseInput(input);

// End the trace (returns duration in ms)
const duration = parseTrace.end();
console.log(`Parsing took ${duration}ms`);

The TraceDetails Interface

The TraceDetails interface defines the structure of trace data:

interface TraceDetails {
  name: string;           // Operation name
  uuid: string;           // Unique trace identifier
  data: any;              // Associated metadata
  startTime: number;      // Timestamp when trace started
  endTime?: number;       // Timestamp when trace ended (if completed)
  children: TraceDetails[]; // Child traces
}

Getting Trace Details

You can retrieve the full trace data structure:

// Get the complete trace hierarchy
const traceData = rootTrace.getDetails();

// The structure includes all child traces
console.log(JSON.stringify(traceData, null, 2));

Rendering Traces

The render method produces a formatted tree representation of the trace:

// Generate human-readable trace output
const traceOutput = rootTrace.render();
console.log(traceOutput);

Example output:

[trace.123e4567-e89b-12d3-a456-426614174000] main-operation (1200 ms) - {"input":"query"}
└─ [trace.234e5678-e89b-12d3-a456-426614174001] parse-input (50 ms) - {"parser":"default"}
   ├─ [trace.345e6789-e89b-12d3-a456-426614174002] tokenize (20 ms) - {"tokens":15}
   └─ [trace.456e7890-e89b-12d3-a456-426614174003] process (1000 ms) - {"model":"gpt-4o"}

Integration with Agents

The trace system is integrated with Agent for detailed operation tracking:

// Create a trace for agent operations
const trace = new Trace('agent-execution', { agent: agent.uuid });

// Pass the trace to the agent's run method
const result = await agent.run(input, trace);

// Analyze the trace after execution
console.log(trace.render());

Integration with Runner

The Runner class automatically creates and manages traces:

// Create a runner
const runner = new Runner(agent);

// Run the agent
const result = await runner.run(input);

// Get the runs trace
const trace = result.trace;

// Or get the last trace for the runner
const lastTrace = runner.getLastTrace();
console.log(lastTrace.render());

// Or get all traces the runner has made
const allTraces = runner.getTraces();

Performance Analysis

Traces can be used to identify performance bottlenecks:

// Get total execution time
const totalTime = rootTrace.end(); // Returns total duration in ms

Agent: Core component that generates traces during execution
Runner: Orchestrates agents and manages trace hierarchy
Loom: Global configuration