Class LangfuseEmbedding

Specialized observation wrapper for tracking text embedding and vector generation operations.

LangfuseEmbedding is designed for observing embedding model interactions that convert text, images, or other content into high-dimensional vector representations. It captures embedding model parameters, input preprocessing, vector characteristics, and performance metrics, making it essential for semantic search, RAG systems, and similarity-based applications.

Primary Use Cases

Text Embeddings: Converting text to vectors for semantic search and similarity
Document Indexing: Creating vector representations for large document collections
Semantic Search: Enabling similarity-based search and content discovery
RAG Preparation: Embedding documents and queries for retrieval-augmented generation
Clustering Analysis: Grouping similar content using vector representations
Recommendation Systems: Content similarity for personalized recommendations

Key Features

Model Tracking: Embedding model selection, version, and parameter monitoring
Input Processing: Text preprocessing, tokenization, and normalization tracking
Vector Analysis: Dimensionality, magnitude, and quality metrics for generated embeddings
Batch Processing: Efficient handling of multiple texts in single embedding operations
Performance Monitoring: Embedding generation speed, cost tracking, and efficiency metrics
Quality Assessment: Vector quality evaluation and embedding effectiveness measurement

Example

// Text embedding generation
const embedding = startObservation('text-embedder', {
  input: {
    texts: [
      'Machine learning is a subset of AI',
      'Deep learning uses neural networks'
    ],
    batchSize: 2
  },
  model: 'text-embedding-ada-002'
}, { asType: 'embedding' });

const embedResult = await generateEmbeddings({
  texts: [
    'Machine learning is a subset of AI',
    'Deep learning uses neural networks'
  ],
  model: 'text-embedding-ada-002'
});

embedding.update({
  output: {
    embeddings: embedResult.vectors,
    count: embedResult.vectors.length,
    dimensions: 1536
  },
  usageDetails: {
    totalTokens: embedResult.tokenCount
  },
  metadata: {
    processingTime: 340
  }
});
embedding.end();

See

startObservation with { asType: 'embedding' } - Factory function
LangfuseRetriever - For using embeddings in vector search
LangfuseGeneration - For LLM operations that may use embeddings

Hierarchy

LangfuseBaseObservation
- LangfuseEmbedding

Index

Constructors

constructor

new LangfuseEmbedding(params: LangfuseEmbeddingParams): LangfuseEmbedding
Parameters
- params: LangfuseEmbeddingParams
Returns LangfuseEmbedding
Overrides LangfuseBaseObservation.constructor
- Defined in tracing/src/spanWrapper.ts:1386

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: LangfuseGenerationAttributes): LangfuseEmbedding
Updates this embedding observation with new attributes.
Parameters
- attributes: LangfuseGenerationAttributes
  Embedding attributes to set
Returns LangfuseEmbedding
This embedding for method chaining
- Defined in tracing/src/spanWrapper.ts:1396

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

Class LangfuseEmbedding

Primary Use Cases

Key Features

Example

See

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns LangfuseEmbedding

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