Class LangfuseEvaluator

Specialized observation wrapper for tracking quality assessment and evaluation operations.

LangfuseEvaluator is designed for observing evaluation systems that assess, score, and validate the quality of AI outputs, content, or system performance. It captures evaluation criteria, scoring methodologies, benchmark comparisons, and quality metrics, making it essential for AI system validation, content moderation, and performance monitoring.

Primary Use Cases

LLM Output Evaluation: Response quality, factual accuracy, and relevance assessment
Content Quality Assessment: Writing quality, tone analysis, and style validation
Automated Testing: System performance validation and regression testing
Bias Detection: Fairness evaluation and bias identification in AI systems
Safety Evaluation: Content safety, harm detection, and compliance checking
Benchmark Comparison: Performance comparison against reference standards

Key Features

Multi-Criteria Scoring: Comprehensive evaluation across multiple quality dimensions
Automated Assessment: AI-powered evaluation using specialized models and algorithms
Human Evaluation: Integration with human reviewers and expert assessment
Benchmark Tracking: Performance comparison against established baselines
Quality Metrics: Detailed scoring with confidence intervals and reliability measures
Trend Analysis: Quality tracking over time with improvement recommendations

Example

// Response quality evaluation
const evaluator = startObservation('response-quality-eval', {
  input: {
    response: 'Machine learning is a subset of artificial intelligence...',
    criteria: ['accuracy', 'completeness', 'clarity']
  }
}, { asType: 'evaluator' });

const evaluation = await evaluateResponse({
  response: 'Machine learning is a subset of artificial intelligence...',
  criteria: ['accuracy', 'completeness', 'clarity']
});

evaluator.update({
  output: {
    overallScore: 0.87,
    criteriaScores: {
      accuracy: 0.92,
      completeness: 0.85,
      clarity: 0.90
    },
    passed: true
  }
});
evaluator.end();

See

startObservation with { asType: 'evaluator' } - Factory function
LangfuseGeneration - For LLM outputs being evaluated
LangfuseGuardrail - For safety and compliance enforcement

Hierarchy

LangfuseBaseObservation
- LangfuseEvaluator

Index

Constructors

constructor

new LangfuseEvaluator(params: LangfuseEvaluatorParams): LangfuseEvaluator
Parameters
- params: LangfuseEvaluatorParams
Returns LangfuseEvaluator
Overrides LangfuseBaseObservation.constructor
- Defined in tracing/src/spanWrapper.ts:1087

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): LangfuseEvaluator
Updates this evaluator observation with new attributes.
Parameters
- attributes: LangfuseSpanAttributes
  Evaluator attributes to set
Returns LangfuseEvaluator
This evaluator for method chaining
- Defined in tracing/src/spanWrapper.ts:1097

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): LangfuseEvaluator
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 LangfuseEvaluator
This observation for method chaining
Inherited from LangfuseBaseObservation.updateTrace
- Defined in tracing/src/spanWrapper.ts:203

Class LangfuseEvaluator

Primary Use Cases

Key Features

Example

See

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns LangfuseEvaluator

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

Returns LangfuseEmbedding

`Readonly`otelSpan

`Readonly`type

`Protected`tracer