Skip to main content

​
Class: Trace

Defined in: src/lib/logger/components/trace.ts:65 Represents a trace (a single turn interaction). Traces capture the complete execution flow of operations, including generations, tool calls, retrievals, spans, and errors happening within one user interaction turn. They provide detailed timing and hierarchical organization of activities within a session or standalone operation. Trace

​
Example

const trace = logger.trace({
  id: 'query-processing-trace',
  name: 'User Query Processing',
  sessionId: 'chat-session-001', // optional
});

// Add input
trace.input('Find information about machine learning');

// Adding components to trace
const generation = trace.generation({
  id: 'llm-generation-001',
  provider: 'openai',
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Explain ML' }],
  modelParameters: { temperature: 0.7 }
});

const retrieval = trace.retrieval({
  id: 'vector-search-001',
  name: 'Knowledge Base Search'
});

const toolCall = trace.toolCall({
  id: 'search-tool-001',
  name: 'external_search',
  description: 'Search external knowledge base',
  args: JSON.stringify({ query: 'machine learning' })
});

// Add output
trace.output('Machine learning is a subset of artificial intelligence...');

​
Extends

​
Constructors

​
Constructor

new Trace(config, writer): Trace
Defined in: src/lib/logger/components/trace.ts:78 Creates a new trace log entry.

​
Parameters

config
TraceConfig Configuration object defining the trace
writer
LogWriter Log writer instance for persisting trace data

​
Returns

Trace

​
Example

const trace = new Trace({
  id: 'recommendation-trace',
  name: 'Product Recommendation Flow',
  sessionId: 'shopping-session-456',
});

​
Overrides

EventEmittingBaseContainer.constructor

​
Accessors

​
evaluate

​
Get Signature

get evaluate(): EvaluateContainer
Defined in: src/lib/logger/components/base.ts:248 Gets the evaluation methods for this container.
Example
container.evaluate.withEvaluators('bias', 'toxicity');
Returns
EvaluateContainer Evaluation methods for configuring and triggering evaluations

​
Inherited from

EventEmittingBaseContainer.evaluate

​
id

​
Get Signature

get id(): string
Defined in: src/lib/logger/components/base.ts:80 Gets the unique identifier for this container.
Returns
string The container’s unique ID

​
Inherited from

EventEmittingBaseContainer.id

​
Methods

​
addAttachment()

addAttachment(attachment): void
Defined in: src/lib/logger/components/trace.ts:199 Adds an attachment to this trace.

​
Parameters

attachment
Attachment The attachment to add (can be of type file, data, or URL)

​
Returns

void void

​
Example

trace.addAttachment({
  id: 'input-document',
  type: 'file',
  path: './uploads/document.pdf',
  tags: { category: 'input' }
});

​
addMetadata()

addMetadata(metadata): void
Defined in: src/lib/logger/components/base.ts:124 Adds metadata to this container for additional context and debugging. Any data type could be added as the value in the metadata record.

​
Parameters

metadata
Record<string, unknown> Key-value pairs of metadata

​
Returns

void void

​
Example

container.addMetadata({
  requestId: 'req-123',
  userAgent: 'Mozilla/5.0...',
  processingTime: 1500
});

​
Inherited from

EventEmittingBaseContainer.addMetadata

​
addTag()

addTag(key, value): void
Defined in: src/lib/logger/components/base.ts:94 Adds a tag to this container for categorization and filtering.

​
Parameters

key
string The tag key
value
string The tag value

​
Returns

void void

​
Example

container.addTag('environment', 'production');
container.addTag('user_type', 'premium');

​
Inherited from

EventEmittingBaseContainer.addTag

​
addToSession()

addToSession(sessionId): void
Defined in: src/lib/logger/components/trace.ts:139 Associates this trace with a session.

​
Parameters

sessionId
string The ID of the session to associate with

​
Returns

void void

​
Example

trace.addToSession('user-session-789');

​
data()

data(): any
Defined in: src/lib/logger/components/base.ts:191 Returns the current data state of this container.

​
Returns

any The container’s data.

​
Inherited from

EventEmittingBaseContainer.data

​
end()

end(): void
Defined in: src/lib/logger/components/base.ts:163 Marks this container as ended and records the end timestamp.

​
Returns

void void

​
Example

// End a container when processing is complete
container.end();

​
Inherited from

EventEmittingBaseContainer.end

​
error()

error(config): Error
Defined in: src/lib/logger/components/trace.ts:265 Creates an error within this trace.

​
Parameters

config
ErrorConfig Configuration for the error

​
Returns

Error A new error instance associated with this trace

​
Example

const error = trace.error({
  id: 'processing-error',
  message: 'Failed to process user input',
  code: 'PROCESSING_FAILED',
  type: 'ProcessingError'
});

​
event()

event(id, name, tags?, metadata?): void
Defined in: src/lib/logger/components/base.ts:291 Emits a custom event within this container.

​
Parameters

id
string Unique identifier for the event
name
string Human-readable name for the event
tags?
Record<string, string> Optional tags for categorizing the event
metadata?
Record<string, unknown> Optional metadata for additional context

​
Returns

void void

​
Example

container.event(
  'checkpoint-1',
  'Processing Milestone',
  { phase: 'preprocessing', status: 'complete' },
  { itemsProcessed: 1000, timeElapsed: 5.2 }
);

​
Inherited from

EventEmittingBaseContainer.event

​
feedback()

feedback(feedback): void
Defined in: src/lib/logger/components/trace.ts:168 Adds feedback to this trace from users.

​
Parameters

feedback
Feedback object containing score and optional comment
comment?
string Optional textual feedback
score
number Numerical score for the trace

​
Returns

void void

​
Example

trace.feedback({
  score: 4,
  comment: 'Good results but could be faster'
});

​
generation()

generation(config): Generation
Defined in: src/lib/logger/components/trace.ts:103 Creates a new generation (LLM call) within this trace.

​
Parameters

config
GenerationConfig Configuration for the generation

​
Returns

Generation A new generation instance associated with this trace

​
Example

const generation = trace.generation({
  id: 'summary-generation',
  provider: 'openai',
  model: 'gpt-4',
  messages: [
    { role: 'system', content: 'Summarize the following text.' },
    { role: 'user', content: 'Long article content...' }
  ],
  modelParameters: { temperature: 0.3, max_tokens: 150 }
});

​
input()

input(input): Trace
Defined in: src/lib/logger/components/trace.ts:375 Sets the input for this trace.

​
Parameters

input
string The input that for this trace

​
Returns

Trace This trace instance for method chaining

​
Example

trace.input('Analyze this customer feedback: "The product is great but shipping was slow"');

​
output()

output(output): Trace
Defined in: src/lib/logger/components/trace.ts:402 Sets the output for this trace.

​
Parameters

output
string The final output or result of this trace execution

​
Returns

Trace This trace instance for method chaining

​
Example

trace.output('Sentiment: Positive (0.7), Issues: Shipping delay, Action: Contact logistics team');

​
retrieval()

retrieval(config): Retrieval
Defined in: src/lib/logger/components/trace.ts:341 Creates a retrieval within this trace.

​
Parameters

config
RetrievalConfig Configuration for the retrieval

​
Returns

Retrieval A new retrieval instance associated with this trace

​
Example

const retrieval = trace.retrieval({
  id: 'knowledge-search',
  name: 'Knowledge Base Search'
});

​
span()

span(config): Span
Defined in: src/lib/logger/components/trace.ts:226 Creates a new span within this trace for hierarchical organization.

​
Parameters

config
SpanConfig Configuration for the span

​
Returns

Span A new span instance associated with this trace

​
Example

const span = trace.span({
  id: 'data-processing-span',
  name: 'Data Processing Pipeline',
});

​
toolCall()

toolCall(config): ToolCall
Defined in: src/lib/logger/components/trace.ts:304 Creates a tool call within this trace.

​
Parameters

config
ToolCallConfig Configuration for the tool call

​
Returns

ToolCall A new tool call instance associated with this trace

​
Example

const toolCall = trace.toolCall({
  id: 'calculator-tool',
  name: 'calculate',
  description: 'Perform mathematical calculations',
  args: JSON.stringify({ expression: '2 + 2' })
});

​
addAttachment_()

static addAttachment_(writer, id, attachment): void
Defined in: src/lib/logger/components/trace.ts:211 Static method to add an attachment to any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
attachment
Attachment The attachment to add

​
Returns

void void

​
addMetadata_()

static addMetadata_(writer, entity, id, metadata): void
Defined in: src/lib/logger/components/base.ts:144 Static method to add metadata to any container by ID.

​
Parameters

writer
LogWriter The log writer instance
entity
Entity The entity type
id
string The container ID
metadata
Record<string, unknown> The metadata to add

​
Returns

void void

​
Inherited from

EventEmittingBaseContainer.addMetadata_

​
addTag_()

static addTag_(writer, entity, id, key, value): void
Defined in: src/lib/logger/components/base.ts:108 Static method to add a tag to any container by ID.

​
Parameters

writer
LogWriter The log writer instance
entity
Entity The entity type
id
string The container ID
key
string The tag key
value
string The tag value

​
Returns

void void

​
Inherited from

EventEmittingBaseContainer.addTag_

​
addToSession_()

static addToSession_(writer, id, sessionId): void
Defined in: src/lib/logger/components/trace.ts:151 Static method to associate any trace with a session by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
sessionId
string The session ID to associate with

​
Returns

void void

​
end_()

static end_(writer, entity, id, data?): void
Defined in: src/lib/logger/components/base.ts:177 Static method to end any container by ID.

​
Parameters

writer
LogWriter The log writer instance
entity
Entity The entity type
id
string The container ID
data?
any Optional additional data to include with the end event

​
Returns

void void

​
Inherited from

EventEmittingBaseContainer.end_

​
error_()

static error_(writer, id, config): Error
Defined in: src/lib/logger/components/trace.ts:282 Static method to create an error associated with any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
config
ErrorConfig Configuration for the error

​
Returns

Error A new error instance

​
evaluate_()

static evaluate_(writer, entity, id): EvaluateContainer
Defined in: src/lib/logger/components/base.ts:260 Static method to get evaluation methods for any evaluatable container by ID.

​
Parameters

writer
LogWriter The log writer instance
entity
Entity The entity type
id
string The container ID

​
Returns

EvaluateContainer Evaluation methods for configuring and triggering evaluations

​
Inherited from

EventEmittingBaseContainer.evaluate_

​
event_()

static event_(writer, entity, id, eventId, name, tags?, metadata?): void
Defined in: src/lib/logger/components/base.ts:318 Static method to emit an event for any event-emitting container by ID.

​
Parameters

writer
LogWriter The log writer instance
entity
Entity The entity type
id
string The container ID
eventId
string Unique identifier for the event
name
string Human-readable name for the event
tags?
Record<string, string> Optional tags for categorizing the event
metadata?
Record<string, unknown> Optional metadata for additional context

​
Returns

void void

​
Inherited from

EventEmittingBaseContainer.event_

​
feedback_()

static feedback_(writer, id, feedback): void
Defined in: src/lib/logger/components/trace.ts:182 Static method to add feedback to any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
feedback
Feedback object
comment?
string Optional textual feedback
score
number Numerical score for the trace

​
Returns

void void

​
generation_()

static generation_(writer, id, config): Generation
Defined in: src/lib/logger/components/trace.ts:121 Static method to create a generation associated with any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
config
GenerationConfig Configuration for the generation

​
Returns

Generation A new generation instance

​
input_()

static input_(writer, id, input): void
Defined in: src/lib/logger/components/trace.ts:388 Static method to set input for any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
input
string The input for the trace

​
Returns

void void

​
output_()

static output_(writer, id, output): void
Defined in: src/lib/logger/components/trace.ts:415 Static method to set output for any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
output
string The output for the trace

​
Returns

void void

​
retrieval_()

static retrieval_(writer, id, config): Retrieval
Defined in: src/lib/logger/components/trace.ts:358 Static method to create a retrieval associated with any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
config
RetrievalConfig Configuration for the retrieval

​
Returns

Retrieval A new retrieval instance

​
span_()

static span_(writer, id, config): Span
Defined in: src/lib/logger/components/trace.ts:243 Static method to create a span associated with any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
config
SpanConfig Configuration for the span

​
Returns

Span A new span instance

​
toolCall_()

static toolCall_(writer, id, config): ToolCall
Defined in: src/lib/logger/components/trace.ts:321 Static method to create a tool call associated with any trace by ID.

​
Parameters

writer
LogWriter The log writer instance
id
string The trace ID
config
ToolCallConfig Configuration for the tool call

​
Returns

ToolCall A new tool call instance