Skip to main content

Class: Span

Defined in: src/lib/logger/components/span.ts:60 Represents a hierarchical span within a trace for grouping. Spans provide fine-grained instrumentation within traces, allowing you to organize sections of complex operations. They can contain all kinds of components within them apart from trace or session (nested spans are allowed). Span

Examples

const span = container.span({
  id: 'authentication-span',
  name: 'User Authentication Process',
});

// Add operations to the span
const generation = span.generation({
  id: 'token-validation',
  provider: 'internal',
  model: 'auth-validator',
  messages: [{ role: 'system', content: 'Validate token' }],
  modelParameters: {}
});
// Nested spans for complex operations
const parentSpan = container.span({
  id: 'document-processing',
  name: 'Document Analysis Pipeline'
});

const childSpan = parentSpan.span({
  id: 'text-extraction',
  name: 'Text Extraction Phase'
});

const retrieval = childSpan.retrieval({
  id: 'knowledge-lookup',
  name: 'Knowledge Base Lookup'
});

Extends

Constructors

Constructor

new Span(config, writer): Span
Defined in: src/lib/logger/components/span.ts:72 Creates a new span log entry.

Parameters

config
SpanConfig Configuration object defining the span
writer
LogWriter Log writer instance for persisting span data

Returns

Span

Example

const span = container.span({
  id: 'data-validation-span',
  name: 'Input Data Validation',
});

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/span.ts:289 Adds an attachment to this span.

Parameters

attachment
Attachment The attachment to add (file, data, or URL)

Returns

void void

Example

span.addAttachment({
  id: 'processing-result',
  type: 'file',
  path: './output/processed_data.json',
  name: 'Processing Results'
});

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

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/span.ts:169 Creates an error within this span.

Parameters

config
ErrorConfig Configuration for the error

Returns

Error A new error instance associated with this span

Example

const error = span.error({
  id: 'validation-error',
  message: 'Input validation failed',
  code: 'INVALID_INPUT',
  type: 'ValidationError'
});

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

generation()

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

Parameters

config
GenerationConfig Configuration for the generation

Returns

Generation A new generation instance associated with this span

Example

const generation = span.generation({
  id: 'validation-check',
  provider: 'openai',
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Validate this input' }],
  modelParameters: { temperature: 0.1 }
});

retrieval()

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

Parameters

config
RetrievalConfig Configuration for the retrieval

Returns

Retrieval A new retrieval instance associated with this span

Example

const retrieval = span.retrieval({
  id: 'context-lookup',
  name: 'Context Database Lookup',
});

retrieval.input('user query context');
retrieval.output(['relevant context 1', 'relevant context 2']);

span()

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

Parameters

config
SpanConfig Configuration for the nested span

Returns

Span A new nested span instance

Example

const childSpan = parentSpan.span({
  id: 'preprocessing-step',
  name: 'Data Preprocessing',
});

toolCall()

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

Parameters

config
ToolCallConfig Configuration for the tool call

Returns

ToolCall A new tool call instance associated with this span

Example

const toolCall = span.toolCall({
  id: 'api-call',
  name: 'external_api_call',
  description: 'Fetch data from external service',
  args: JSON.stringify({ endpoint: '/users', id: 123 })
});

toolCall.result('{"name": "John", "email": "[email protected]"}');

addAttachment_()

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

Parameters

writer
LogWriter The log writer instance
id
string The span 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_

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/span.ts:186 Static method to create an error associated with any span by ID.

Parameters

writer
LogWriter The log writer instance
id
string The span 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_

generation_()

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

Parameters

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

Returns

Generation A new generation instance

retrieval_()

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

Parameters

writer
LogWriter The log writer instance
id
string The span 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/span.ts:147 Static method to create a nested span associated with any span by ID.

Parameters

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

Returns

Span A new nested span instance

toolCall_()

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

Parameters

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

Returns

ToolCall A new tool call instance