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:1115

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:166

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:175

setTraceAsPublic

setTraceAsPublic(): LangfuseEvaluator
Make the trace this observation belongs to publicly accessible via its URL.

When a trace is published, anyone with the trace link can view the full trace without needing to be logged in to Langfuse. This action cannot be undone programmatically - once any span in a trace is published, the entire trace becomes public.

Returns LangfuseEvaluator
The observation instance for method chaining
Example
```
const span = startObservation('my-operation');
span.setTraceAsPublic();
```
Inherited from LangfuseBaseObservation.setTraceAsPublic
- Defined in tracing/src/spanWrapper.ts:229

setTraceIO

setTraceIO(attributes: LangfuseTraceIOAttributes): LangfuseEvaluator
Set trace-level input and output for the trace this observation belongs to.
Parameters
- attributes: LangfuseTraceIOAttributes
  Input and output data to associate with the trace
Returns LangfuseEvaluator
The observation instance for method chaining
Deprecated
This is a legacy method for backward compatibility with Langfuse platform features that still rely on trace-level input/output (e.g., legacy LLM-as-a-judge evaluators). It will be removed in a future major version.

For setting other trace attributes (userId, sessionId, metadata, tags, version), use propagateAttributes instead.
Example
```
const span = startObservation('my-operation');
span.setTraceIO({
  input: { query: 'user question' },
  output: { response: 'assistant answer' }
});
```
Inherited from LangfuseBaseObservation.setTraceIO
- Defined in tracing/src/spanWrapper.ts:207

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:1125

updateOtelSpanAttributes

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

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

setTraceAsPublic

Returns LangfuseEvaluator

Example

setTraceIO

Parameters

Returns LangfuseEvaluator

Deprecated

Example

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

`Readonly`otelSpan

`Readonly`type

`Protected`tracer