Class LangfuseSpan

General-purpose observation wrapper for tracking operations, functions, and workflows.

LangfuseSpan is the default and most versatile observation type, designed for tracing any operation that has a defined start and end time. It serves as the foundation for building hierarchical traces and can contain any other observation type as children.

Primary Use Cases

Business Logic: User workflows, order processing, data transformations
API Operations: REST endpoint handling, database queries, external service calls
System Operations: File I/O, network requests, background jobs
Pipeline Steps: Data processing stages, validation steps, orchestration
Application Functions: Any measurable operation in your application

Key Features

Hierarchical Structure: Can contain child observations of any type
Flexible Attributes: Supports arbitrary input, output, and metadata
Duration Tracking: Automatically measures execution time from start to end
Status Monitoring: Tracks success/failure states and error conditions
Context Propagation: Maintains trace context for distributed operations

Span Lifecycle

Creation: Span starts automatically when created
Updates: Add input data, intermediate state, metadata as needed
Child Operations: Create nested observations for sub-operations
Completion: Update with final output and call .end() to finish

Example

// Basic span tracking
const span = startObservation('user-authentication', {
  input: { username: 'john_doe', method: 'oauth' },
  metadata: { provider: 'google' }
});

try {
  const user = await authenticateUser(credentials);
  span.update({
    output: { userId: user.id, success: true }
  });
} catch (error) {
  span.update({
    level: 'ERROR',
    output: { success: false, error: error.message }
  });
} finally {
  span.end();
}

// Nested operations
const workflow = startObservation('order-processing', {
  input: { orderId: 'ord_123' }
});

const validation = workflow.startObservation('validation', {
  input: { items: cartItems }
});
validation.update({ output: { valid: true } });
validation.end();

const payment = workflow.startObservation('payment', {
  input: { amount: 100 }
});
payment.update({ output: { status: 'completed' } });
payment.end();

workflow.update({
  output: { status: 'confirmed', steps: 2 }
});
workflow.end();

See

startObservation - Factory function for creating spans
startActiveObservation - Function-scoped span creation
LangfuseGeneration - For LLM and AI model interactions
LangfuseEvent - For point-in-time occurrences

Hierarchy

LangfuseBaseObservation
- LangfuseSpan

Index

Constructors

constructor

new LangfuseSpan(params: LangfuseSpanParams): LangfuseSpan
Parameters
- params: LangfuseSpanParams
Returns LangfuseSpan
Overrides LangfuseBaseObservation.constructor
- Defined in tracing/src/spanWrapper.ts:536

Properties

id

id: string

The span ID from the OpenTelemetry span context

`Readonly`otelSpan

otelSpan: Span

The underlying OpenTelemetry span

traceId

traceId: string

The trace ID from the OpenTelemetry span context

`Readonly`type

type: LangfuseObservationType

The underlying OpenTelemetry span

Accessors

`Protected`tracer

get tracer(): Tracer
Gets the Langfuse OpenTelemetry tracer instance

Returns Tracer
Inherited from LangfuseBaseObservation.tracer
- Defined in tracing/src/spanWrapper.ts:175

Methods

end

end(endTime?: TimeInput): void
Ends the observation, marking it as complete.
Parameters
- OptionalendTime: TimeInput
  Optional end time, defaults to current time
Returns void
Inherited from LangfuseBaseObservation.end
- Defined in tracing/src/spanWrapper.ts:184

startObservation

startObservation(
    name: string,
    attributes: LangfuseGenerationAttributes,
    options: { asType: "generation" },
): LangfuseGeneration

Creates a new child observation within this observation's context with full type safety.

This method enables hierarchical tracing by creating child observations that inherit the parent's trace context. It supports all observation types with automatic TypeScript type inference based on the asType parameter, ensuring compile-time safety for attributes and return types.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseGenerationAttributes
Type-specific attributes (varies by observation type)
options: { asType: "generation" }
Configuration including observation type (defaults to 'span')

Returns LangfuseGeneration

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "event" },
): LangfuseEvent

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "event" }
Configuration including observation type (defaults to 'span')

Returns LangfuseEvent

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "agent" },
): LangfuseAgent

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "agent" }
Configuration including observation type (defaults to 'span')

Returns LangfuseAgent

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "tool" },
): LangfuseTool

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "tool" }
Configuration including observation type (defaults to 'span')

Returns LangfuseTool

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "chain" },
): LangfuseChain

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "chain" }
Configuration including observation type (defaults to 'span')

Returns LangfuseChain

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "retriever" },
): LangfuseRetriever

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "retriever" }
Configuration including observation type (defaults to 'span')

Returns LangfuseRetriever

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "evaluator" },
): LangfuseEvaluator

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "evaluator" }
Configuration including observation type (defaults to 'span')

Returns LangfuseEvaluator

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseSpanAttributes,
    options: { asType: "guardrail" },
): LangfuseGuardrail

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
options: { asType: "guardrail" }
Configuration including observation type (defaults to 'span')

Returns LangfuseGuardrail

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes: LangfuseGenerationAttributes,
    options: { asType: "embedding" },
): LangfuseEmbedding

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
attributes: LangfuseGenerationAttributes
Type-specific attributes (varies by observation type)
options: { asType: "embedding" }
Configuration including observation type (defaults to 'span')

Returns LangfuseEmbedding

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

startObservation(
    name: string,
    attributes?: LangfuseSpanAttributes,
    options?: { asType?: "span" },
): LangfuseSpan

Creates a new child observation within this observation's context with full type safety.

Hierarchy & Context

Child observations automatically inherit the parent's trace ID and span context
Creates proper parent-child relationships in the trace structure
Enables distributed tracing across nested operations
Maintains correlation between related operations

Type Safety

Return type is automatically inferred from asType parameter
Attributes parameter is type-checked based on observation type
Compile-time validation prevents type mismatches
Full IntelliSense support for observation-specific attributes

Parameters

name: string
Descriptive name for the child observation
Optionalattributes: LangfuseSpanAttributes
Type-specific attributes (varies by observation type)
Optionaloptions: { asType?: "span" }
Configuration including observation type (defaults to 'span')

Returns LangfuseSpan

Strongly-typed observation instance based on asType

Example

// Within any observation (span, generation, agent, etc.)
const parentObservation = startObservation('ai-workflow');

// Create child span (default)
const dataProcessing = parentObservation.startObservation('data-processing', {
  input: { userId: '123', dataSize: 1024 },
  metadata: { processor: 'fast-lane', version: '2.1' }
}); // Returns LangfuseSpan

// Create child generation with full LLM attributes
const llmCall = parentObservation.startObservation('openai-gpt-4', {
  input: [{ role: 'system', content: 'You are a helpful assistant' },
          { role: 'user', content: 'Explain machine learning' }],
  model: 'gpt-4-turbo',
  modelParameters: {
    temperature: 0.7,
    maxTokens: 500,
    topP: 1.0
  },
  metadata: { priority: 'high', timeout: 30000 }
}, { asType: 'generation' }); // Returns LangfuseGeneration

// Create child agent for complex reasoning
const reasoningAgent = parentObservation.startObservation('reasoning-agent', {
  input: {
    task: 'Analyze market trends',
    context: 'Q4 2024 financial data'
  },
  metadata: {
    model: 'gpt-4',
    tools: ['calculator', 'web-search', 'data-analysis'],
    maxIterations: 5
  }
}, { asType: 'agent' }); // Returns LangfuseAgent

// Create child tool for external API calls
const apiCall = reasoningAgent.startObservation('market-data-api', {
  input: {
    endpoint: '/market/trends',
    params: { symbol: 'AAPL', period: '1Y' }
  },
  metadata: {
    provider: 'alpha-vantage',
    rateLimit: 5,
    timeout: 10000
  }
}, { asType: 'tool' }); // Returns LangfuseTool

// Create child retriever for document search
const docSearch = parentObservation.startObservation('document-retrieval', {
  input: {
    query: 'sustainable energy solutions',
    filters: { year: '2024', category: 'research' },
    topK: 10
  },
  metadata: {
    vectorStore: 'pinecone',
    embeddingModel: 'text-embedding-ada-002',
    similarity: 'cosine'
  }
}, { asType: 'retriever' }); // Returns LangfuseRetriever

// Create child evaluator for quality assessment
const qualityCheck = parentObservation.startObservation('response-evaluator', {
  input: {
    response: llmCall.output?.content,
    reference: 'Expected high-quality explanation',
    criteria: ['accuracy', 'clarity', 'completeness']
  },
  metadata: {
    evaluator: 'custom-bert-scorer',
    threshold: 0.8,
    metrics: ['bleu', 'rouge', 'semantic-similarity']
  }
}, { asType: 'evaluator' }); // Returns LangfuseEvaluator

// Create child guardrail for safety checking
const safetyCheck = parentObservation.startObservation('content-guardrail', {
  input: {
    text: llmCall.output?.content,
    policies: ['no-harmful-content', 'no-personal-info', 'professional-tone']
  },
  metadata: {
    guardrailVersion: 'v2.1',
    strictMode: true,
    confidence: 0.95
  }
}, { asType: 'guardrail' }); // Returns LangfuseGuardrail

// Create child embedding for vector generation
const textEmbedding = parentObservation.startObservation('text-embedder', {
  input: {
    texts: ['Document summary', 'Key insights', 'Conclusions'],
    batchSize: 3
  },
  model: 'text-embedding-ada-002',
  metadata: {
    dimensions: 1536,
    normalization: 'l2',
    purpose: 'semantic-search'
  }
}, { asType: 'embedding' }); // Returns LangfuseEmbedding

// Create child event for point-in-time logging
const userAction = parentObservation.startObservation('user-interaction', {
  input: {
    action: 'button-click',
    element: 'generate-report',
    timestamp: new Date().toISOString()
  },
  level: 'DEFAULT',
  metadata: {
    sessionId: 'sess_123',
    userId: 'user_456',
    browser: 'Chrome 120.0'
  }
}, { asType: 'event' }); // Returns LangfuseEvent (auto-ended)

// Chain operations - each child inherits context
dataProcessing.update({ output: { processed: true, records: 1000 } });
dataProcessing.end();

llmCall.update({
  output: { role: 'assistant', content: 'Machine learning is...' },
  usageDetails: { promptTokens: 25, completionTokens: 150 }
});
llmCall.end();

parentObservation.update({
  output: {
    workflowCompleted: true,
    childOperations: 8,
    totalDuration: Date.now() - startTime
  }
});
parentObservation.end();

See

startObservation for creating root-level observations
startActiveObservation for function-scoped child observations

update

update(attributes: LangfuseSpanAttributes): LangfuseSpan
Updates this span with new attributes.
Parameters
- attributes: LangfuseSpanAttributes
  Span attributes to set
Returns LangfuseSpan
This span for method chaining
Example
```
span.update({
  output: { result: 'success' },
  level: 'DEFAULT',
  metadata: { duration: 150 }
});
```
- Defined in tracing/src/spanWrapper.ts:555

updateOtelSpanAttributes

updateOtelSpanAttributes(attributes: LangfuseObservationAttributes): void
Parameters
- attributes: LangfuseObservationAttributes
Returns void
Inherited from LangfuseBaseObservation.updateOtelSpanAttributes
- Defined in tracing/src/spanWrapper.ts:188

updateTrace

updateTrace(attributes: LangfuseTraceAttributes): LangfuseSpan
Updates the parent trace with new attributes.

This sets trace-level attributes that apply to the entire trace, not just this specific observation.
Parameters
- attributes: LangfuseTraceAttributes
  Trace attributes to set
Returns LangfuseSpan
This observation for method chaining
Inherited from LangfuseBaseObservation.updateTrace
- Defined in tracing/src/spanWrapper.ts:203

Class LangfuseSpan

Primary Use Cases

Key Features

Span Lifecycle

Example

See

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns LangfuseSpan

Properties

id

ReadonlyotelSpan

traceId

Readonlytype

Accessors

Protectedtracer

Returns Tracer

Methods

end

Parameters

Returns void

startObservation

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseGeneration

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseEvent

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseAgent

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseTool

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseChain

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseRetriever

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseEvaluator

Example

See

Hierarchy & Context

Type Safety

Parameters

Returns LangfuseGuardrail

Example

See

Hierarchy & Context

Type Safety

Parameters

`Readonly`otelSpan

`Readonly`type

`Protected`tracer