0
# Observation Types
1

2
Langfuse provides 10 specialized observation classes, each optimized for specific use cases in AI and software workflows. Each observation type shares common methods while providing semantic clarity for different operation types.
3

4
## Overview
5

6
All observation types extend a common base class and share core functionality:
7

8
- **Common Properties**: `id`, `traceId`, `otelSpan`, `type`
9
- **Common Methods**: `update()`, `end()`, `updateTrace()`, `startObservation()`
10
- **Type-Specific Semantics**: Each type provides semantic meaning for specific operations
11

12
```typescript { .api }
13
type LangfuseObservation =
14
  | LangfuseSpan
15
  | LangfuseGeneration
16
  | LangfuseEvent
17
  | LangfuseAgent
18
  | LangfuseTool
19
  | LangfuseChain
20
  | LangfuseRetriever
21
  | LangfuseEvaluator
22
  | LangfuseGuardrail
23
  | LangfuseEmbedding;
24
```
25

26
## LangfuseSpan
27

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

30
```typescript { .api }
31
/**
32
 * General-purpose observation wrapper for tracking operations, functions, and workflows.
33
 */
34
class LangfuseSpan {
35
  /** Unique identifier for this observation */
36
  readonly id: string;
37
  /** Trace ID containing this observation */
38
  readonly traceId: string;
39
  /** Underlying OpenTelemetry span */
40
  readonly otelSpan: Span;
41
  /** Observation type */
42
  readonly type: "span";
43

44
  /**
45
   * Updates this span with new attributes.
46
   */
47
  update(attributes: LangfuseSpanAttributes): LangfuseSpan;
48

49
  /**
50
   * Ends the observation.
51
   */
52
  end(endTime?: Date | number): void;
53

54
  /**
55
   * Updates the parent trace.
56
   */
57
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseSpan;
58

59
  /**
60
   * Creates a child observation.
61
   */
62
  startObservation(
63
    name: string,
64
    attributes?: LangfuseObservationAttributes,
65
    options?: { asType?: LangfuseObservationType }
66
  ): LangfuseObservation;
67
}
68
```
69

70
### Primary Use Cases
71

72
- Business logic operations
73
- API endpoint handling
74
- Data processing workflows
75
- System operations
76
- Background jobs
77

78
### Example
79

80
```typescript
81
import { startObservation } from '@langfuse/tracing';
82

83
const span = startObservation('user-authentication', {
84
  input: { username: 'john_doe', method: 'oauth' },
85
  metadata: { provider: 'google' }
86
});
87

88
try {
89
  const user = await authenticateUser(credentials);
90
  span.update({
91
    output: { userId: user.id, success: true }
92
  });
93
} catch (error) {
94
  span.update({
95
    level: 'ERROR',
96
    statusMessage: error.message
97
  });
98
  throw error;
99
} finally {
100
  span.end();
101
}
102
```
103

104
## LangfuseGeneration
105

106
Specialized observation for LLM calls, text generation, and AI model interactions.
107

108
```typescript { .api }
109
/**
110
 * Specialized observation for tracking LLM interactions and AI model calls.
111
 */
112
class LangfuseGeneration {
113
  readonly id: string;
114
  readonly traceId: string;
115
  readonly otelSpan: Span;
116
  readonly type: "generation";
117

118
  /**
119
   * Updates this generation with new attributes including LLM-specific fields.
120
   */
121
  update(attributes: LangfuseGenerationAttributes): LangfuseGeneration;
122

123
  end(endTime?: Date | number): void;
124
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseGeneration;
125
  startObservation(
126
    name: string,
127
    attributes?: LangfuseObservationAttributes,
128
    options?: { asType?: LangfuseObservationType }
129
  ): LangfuseObservation;
130
}
131

132
interface LangfuseGenerationAttributes extends LangfuseSpanAttributes {
133
  /** Timestamp when the model started generating completion */
134
  completionStartTime?: Date;
135
  /** Name of the language model used */
136
  model?: string;
137
  /** Parameters passed to the model */
138
  modelParameters?: { [key: string]: string | number };
139
  /** Token usage and other model-specific usage metrics */
140
  usageDetails?: { [key: string]: number };
141
  /** Cost breakdown for the generation */
142
  costDetails?: { [key: string]: number };
143
  /** Information about the prompt used */
144
  prompt?: { name: string; version: number; isFallback: boolean };
145
}
146
```
147

148
### Primary Use Cases
149

150
- OpenAI, Anthropic, Cohere API calls
151
- Chat completions
152
- Text generation and summarization
153
- Code generation
154
- RAG generation steps
155

156
### Example
157

158
```typescript
159
const generation = startObservation('openai-gpt-4', {
160
  model: 'gpt-4-turbo',
161
  input: [
162
    { role: 'system', content: 'You are a helpful assistant.' },
163
    { role: 'user', content: 'Explain quantum computing' }
164
  ],
165
  modelParameters: { temperature: 0.7, maxTokens: 500 }
166
}, { asType: 'generation' });
167

168
const response = await openai.chat.completions.create({
169
  model: 'gpt-4-turbo',
170
  messages: generation.attributes.input,
171
  temperature: 0.7,
172
  max_tokens: 500
173
});
174

175
generation.update({
176
  output: response.choices[0].message,
177
  usageDetails: {
178
    promptTokens: response.usage.prompt_tokens,
179
    completionTokens: response.usage.completion_tokens,
180
    totalTokens: response.usage.total_tokens
181
  },
182
  costDetails: { totalCost: 0.025, currency: 'USD' }
183
});
184

185
generation.end();
186
```
187

188
## LangfuseEvent
189

190
Observation for point-in-time occurrences or log entries (automatically ended).
191

192
```typescript { .api }
193
/**
194
 * Observation for point-in-time occurrences or log entries.
195
 * Events are automatically ended at their timestamp.
196
 */
197
class LangfuseEvent {
198
  readonly id: string;
199
  readonly traceId: string;
200
  readonly otelSpan: Span;
201
  readonly type: "event";
202

203
  // Events are automatically ended at creation
204
  // No update() method - events are immutable after creation
205
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseEvent;
206
  startObservation(
207
    name: string,
208
    attributes?: LangfuseObservationAttributes,
209
    options?: { asType?: LangfuseObservationType }
210
  ): LangfuseObservation;
211
}
212
```
213

214
### Primary Use Cases
215

216
- User actions and interactions
217
- System events
218
- Log entries within traces
219
- Instant notifications
220
- Checkpoint markers
221

222
### Example
223

224
```typescript
225
// Events are automatically ended at creation
226
const event = startObservation('user-login', {
227
  input: {
228
    userId: '123',
229
    method: 'oauth',
230
    timestamp: new Date().toISOString()
231
  },
232
  level: 'DEFAULT',
233
  metadata: {
234
    ip: '192.168.1.1',
235
    userAgent: 'Chrome/120.0',
236
    sessionId: 'sess_456'
237
  }
238
}, { asType: 'event' });
239

240
// No need to call event.end() - already ended
241
```
242

243
## LangfuseAgent
244

245
Specialized observation for AI agent workflows with tool usage and autonomous operations.
246

247
```typescript { .api }
248
/**
249
 * Specialized observation for tracking AI agent workflows.
250
 */
251
class LangfuseAgent {
252
  readonly id: string;
253
  readonly traceId: string;
254
  readonly otelSpan: Span;
255
  readonly type: "agent";
256

257
  update(attributes: LangfuseAgentAttributes): LangfuseAgent;
258
  end(endTime?: Date | number): void;
259
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseAgent;
260
  startObservation(
261
    name: string,
262
    attributes?: LangfuseObservationAttributes,
263
    options?: { asType?: LangfuseObservationType }
264
  ): LangfuseObservation;
265
}
266

267
type LangfuseAgentAttributes = LangfuseSpanAttributes;
268
```
269

270
### Primary Use Cases
271

272
- ReAct, AutoGPT, LangGraph agents
273
- Function calling agents
274
- Multi-step reasoning workflows
275
- Planning and execution agents
276
- Conversational agents with memory
277
- Code generation agents
278

279
### Example
280

281
```typescript
282
const agent = startObservation('research-agent', {
283
  input: {
284
    task: 'Research renewable energy trends',
285
    tools: ['web-search', 'summarizer'],
286
    maxIterations: 3
287
  },
288
  metadata: { model: 'gpt-4', strategy: 'react' }
289
}, { asType: 'agent' });
290

291
// Agent uses tools
292
const searchTool = agent.startObservation('web-search', {
293
  input: { query: 'renewable energy 2024' }
294
}, { asType: 'tool' });
295

296
const results = await webSearch('renewable energy 2024');
297
searchTool.update({ output: results });
298
searchTool.end();
299

300
// Agent generates response
301
const generation = agent.startObservation('synthesize-findings', {
302
  input: results,
303
  model: 'gpt-4'
304
}, { asType: 'generation' });
305

306
const response = await llm.generate(results);
307
generation.update({ output: response });
308
generation.end();
309

310
agent.update({
311
  output: {
312
    completed: true,
313
    toolsUsed: 1,
314
    iterationsRequired: 1,
315
    finalResponse: response
316
  },
317
  metadata: { efficiency: 0.85, qualityScore: 0.92 }
318
});
319

320
agent.end();
321
```
322

323
## LangfuseTool
324

325
Specialized observation for individual tool calls and external API interactions.
326

327
```typescript { .api }
328
/**
329
 * Specialized observation for tracking tool calls and API interactions.
330
 */
331
class LangfuseTool {
332
  readonly id: string;
333
  readonly traceId: string;
334
  readonly otelSpan: Span;
335
  readonly type: "tool";
336

337
  update(attributes: LangfuseToolAttributes): LangfuseTool;
338
  end(endTime?: Date | number): void;
339
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseTool;
340
  startObservation(
341
    name: string,
342
    attributes?: LangfuseObservationAttributes,
343
    options?: { asType?: LangfuseObservationType }
344
  ): LangfuseObservation;
345
}
346

347
type LangfuseToolAttributes = LangfuseSpanAttributes;
348
```
349

350
### Primary Use Cases
351

352
- OpenAI function calls
353
- External API requests
354
- Database operations
355
- System tools and commands
356
- Search tools
357
- Content processing tools
358

359
### Example
360

361
```typescript
362
const tool = startObservation('web-search', {
363
  input: {
364
    query: 'latest AI developments',
365
    maxResults: 10
366
  },
367
  metadata: { provider: 'google-api', timeout: 5000 }
368
}, { asType: 'tool' });
369

370
try {
371
  const results = await webSearch('latest AI developments');
372

373
  tool.update({
374
    output: {
375
      results: results,
376
      count: results.length,
377
      relevanceScore: 0.89
378
    },
379
    metadata: { latency: 1200, cacheHit: false }
380
  });
381
} catch (error) {
382
  tool.update({
383
    level: 'ERROR',
384
    statusMessage: 'Search failed',
385
    output: { error: error.message }
386
  });
387
} finally {
388
  tool.end();
389
}
390
```
391

392
## LangfuseChain
393

394
Specialized observation for structured multi-step workflows and process chains.
395

396
```typescript { .api }
397
/**
398
 * Specialized observation for tracking multi-step workflows.
399
 */
400
class LangfuseChain {
401
  readonly id: string;
402
  readonly traceId: string;
403
  readonly otelSpan: Span;
404
  readonly type: "chain";
405

406
  update(attributes: LangfuseChainAttributes): LangfuseChain;
407
  end(endTime?: Date | number): void;
408
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseChain;
409
  startObservation(
410
    name: string,
411
    attributes?: LangfuseObservationAttributes,
412
    options?: { asType?: LangfuseObservationType }
413
  ): LangfuseObservation;
414
}
415

416
type LangfuseChainAttributes = LangfuseSpanAttributes;
417
```
418

419
### Primary Use Cases
420

421
- ETL pipelines
422
- LangChain workflows
423
- RAG pipelines
424
- Multi-model workflows
425
- Content production pipelines
426
- Business process automation
427

428
### Example
429

430
```typescript
431
const chain = startObservation('rag-pipeline', {
432
  input: {
433
    query: 'What is renewable energy?',
434
    steps: ['retrieval', 'generation']
435
  },
436
  metadata: { vectorDb: 'pinecone', model: 'gpt-4' }
437
}, { asType: 'chain' });
438

439
// Step 1: Document retrieval
440
const retrieval = chain.startObservation('document-retrieval', {
441
  input: { query: 'renewable energy' }
442
}, { asType: 'retriever' });
443

444
const docs = await vectorSearch('renewable energy');
445
retrieval.update({ output: { documents: docs, count: docs.length } });
446
retrieval.end();
447

448
// Step 2: Generate response
449
const generation = chain.startObservation('response-generation', {
450
  input: { query: 'What is renewable energy?', context: docs },
451
  model: 'gpt-4'
452
}, { asType: 'generation' });
453

454
const response = await llm.generate({ prompt, context: docs });
455
generation.update({ output: response });
456
generation.end();
457

458
chain.update({
459
  output: {
460
    finalResponse: response,
461
    stepsCompleted: 2,
462
    documentsUsed: docs.length,
463
    pipelineEfficiency: 0.87
464
  }
465
});
466

467
chain.end();
468
```
469

470
## LangfuseRetriever
471

472
Specialized observation for document retrieval and search operations.
473

474
```typescript { .api }
475
/**
476
 * Specialized observation for tracking document retrieval operations.
477
 */
478
class LangfuseRetriever {
479
  readonly id: string;
480
  readonly traceId: string;
481
  readonly otelSpan: Span;
482
  readonly type: "retriever";
483

484
  update(attributes: LangfuseRetrieverAttributes): LangfuseRetriever;
485
  end(endTime?: Date | number): void;
486
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseRetriever;
487
  startObservation(
488
    name: string,
489
    attributes?: LangfuseObservationAttributes,
490
    options?: { asType?: LangfuseObservationType }
491
  ): LangfuseObservation;
492
}
493

494
type LangfuseRetrieverAttributes = LangfuseSpanAttributes;
495
```
496

497
### Primary Use Cases
498

499
- Vector similarity search
500
- Full-text search
501
- Knowledge base queries
502
- RAG retrieval steps
503
- Recommendation systems
504
- Document mining
505

506
### Example
507

508
```typescript
509
const retriever = startObservation('vector-search', {
510
  input: {
511
    query: 'machine learning applications',
512
    topK: 10,
513
    similarityThreshold: 0.7
514
  },
515
  metadata: {
516
    vectorDB: 'pinecone',
517
    embeddingModel: 'text-embedding-ada-002',
518
    similarity: 'cosine'
519
  }
520
}, { asType: 'retriever' });
521

522
const results = await vectorDB.search({
523
  query: 'machine learning applications',
524
  topK: 10,
525
  threshold: 0.7
526
});
527

528
retriever.update({
529
  output: {
530
    documents: results,
531
    count: results.length,
532
    avgSimilarity: 0.89
533
  },
534
  metadata: { searchLatency: 150, cacheHit: false }
535
});
536

537
retriever.end();
538
```
539

540
## LangfuseEvaluator
541

542
Specialized observation for quality assessment and evaluation operations.
543

544
```typescript { .api }
545
/**
546
 * Specialized observation for tracking evaluation operations.
547
 */
548
class LangfuseEvaluator {
549
  readonly id: string;
550
  readonly traceId: string;
551
  readonly otelSpan: Span;
552
  readonly type: "evaluator";
553

554
  update(attributes: LangfuseEvaluatorAttributes): LangfuseEvaluator;
555
  end(endTime?: Date | number): void;
556
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseEvaluator;
557
  startObservation(
558
    name: string,
559
    attributes?: LangfuseObservationAttributes,
560
    options?: { asType?: LangfuseObservationType }
561
  ): LangfuseObservation;
562
}
563

564
type LangfuseEvaluatorAttributes = LangfuseSpanAttributes;
565
```
566

567
### Primary Use Cases
568

569
- LLM output evaluation
570
- Content quality assessment
571
- Automated testing
572
- Bias detection
573
- Safety evaluation
574
- Benchmark comparison
575

576
### Example
577

578
```typescript
579
const evaluator = startObservation('response-quality-eval', {
580
  input: {
581
    response: 'Machine learning is a subset of artificial intelligence...',
582
    reference: 'Expected high-quality explanation',
583
    criteria: ['accuracy', 'completeness', 'clarity']
584
  },
585
  metadata: { evaluator: 'custom-bert-scorer', threshold: 0.8 }
586
}, { asType: 'evaluator' });
587

588
const evaluation = await evaluateResponse({
589
  response: inputText,
590
  criteria: ['accuracy', 'completeness', 'clarity']
591
});
592

593
evaluator.update({
594
  output: {
595
    overallScore: 0.87,
596
    criteriaScores: {
597
      accuracy: 0.92,
598
      completeness: 0.85,
599
      clarity: 0.90
600
    },
601
    passed: true,
602
    grade: 'excellent'
603
  }
604
});
605

606
evaluator.end();
607
```
608

609
## LangfuseGuardrail
610

611
Specialized observation for safety checks and compliance enforcement.
612

613
```typescript { .api }
614
/**
615
 * Specialized observation for tracking safety and compliance checks.
616
 */
617
class LangfuseGuardrail {
618
  readonly id: string;
619
  readonly traceId: string;
620
  readonly otelSpan: Span;
621
  readonly type: "guardrail";
622

623
  update(attributes: LangfuseGuardrailAttributes): LangfuseGuardrail;
624
  end(endTime?: Date | number): void;
625
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseGuardrail;
626
  startObservation(
627
    name: string,
628
    attributes?: LangfuseObservationAttributes,
629
    options?: { asType?: LangfuseObservationType }
630
  ): LangfuseObservation;
631
}
632

633
type LangfuseGuardrailAttributes = LangfuseSpanAttributes;
634
```
635

636
### Primary Use Cases
637

638
- Content moderation
639
- PII detection
640
- Toxicity filtering
641
- Regulatory compliance
642
- Bias mitigation
643
- Privacy protection
644

645
### Example
646

647
```typescript
648
const guardrail = startObservation('content-safety-check', {
649
  input: {
650
    content: userMessage,
651
    policies: ['no-toxicity', 'no-hate-speech', 'no-pii'],
652
    strictMode: true
653
  },
654
  metadata: { guardrailVersion: 'v2.1', confidence: 0.95 }
655
}, { asType: 'guardrail' });
656

657
const safetyCheck = await checkContentSafety({
658
  text: userMessage,
659
  policies: ['no-toxicity', 'no-hate-speech']
660
});
661

662
guardrail.update({
663
  output: {
664
    safe: safetyCheck.safe,
665
    riskScore: 0.15,
666
    violations: [],
667
    action: 'allow'
668
  }
669
});
670

671
guardrail.end();
672
```
673

674
## LangfuseEmbedding
675

676
Specialized observation for text embedding and vector generation operations.
677

678
```typescript { .api }
679
/**
680
 * Specialized observation for tracking embedding generation.
681
 */
682
class LangfuseEmbedding {
683
  readonly id: string;
684
  readonly traceId: string;
685
  readonly otelSpan: Span;
686
  readonly type: "embedding";
687

688
  update(attributes: LangfuseEmbeddingAttributes): LangfuseEmbedding;
689
  end(endTime?: Date | number): void;
690
  updateTrace(attributes: LangfuseTraceAttributes): LangfuseEmbedding;
691
  startObservation(
692
    name: string,
693
    attributes?: LangfuseObservationAttributes,
694
    options?: { asType?: LangfuseObservationType }
695
  ): LangfuseObservation;
696
}
697

698
// Inherits generation attributes including model, usage, cost
699
type LangfuseEmbeddingAttributes = LangfuseGenerationAttributes;
700
```
701

702
### Primary Use Cases
703

704
- Text-to-vector conversion
705
- Document indexing
706
- Semantic search preparation
707
- RAG document embedding
708
- Clustering analysis
709
- Similarity computation
710

711
### Example
712

713
```typescript
714
const embedding = startObservation('text-embedder', {
715
  input: {
716
    texts: [
717
      'Machine learning is a subset of AI',
718
      'Deep learning uses neural networks'
719
    ],
720
    batchSize: 2
721
  },
722
  model: 'text-embedding-ada-002',
723
  metadata: { dimensions: 1536, normalization: 'l2' }
724
}, { asType: 'embedding' });
725

726
const embedResult = await generateEmbeddings({
727
  texts: embedding.attributes.input.texts,
728
  model: 'text-embedding-ada-002'
729
});
730

731
embedding.update({
732
  output: {
733
    embeddings: embedResult.vectors,
734
    count: embedResult.vectors.length,
735
    dimensions: 1536
736
  },
737
  usageDetails: { totalTokens: embedResult.tokenCount },
738
  metadata: { processingTime: 340 }
739
});
740

741
embedding.end();
742
```
743

744
## Common Properties
745

746
All observation types share these properties:
747

748
```typescript { .api }
749
interface CommonObservationProperties {
750
  /** Unique identifier for this observation (OpenTelemetry span ID) */
751
  readonly id: string;
752

753
  /** Identifier of the parent trace containing this observation */
754
  readonly traceId: string;
755

756
  /** Direct access to the underlying OpenTelemetry span */
757
  readonly otelSpan: Span;
758

759
  /** The observation type */
760
  readonly type: LangfuseObservationType;
761
}
762
```
763

764
## Common Methods
765

766
All observation types support these methods:
767

768
### update()
769

770
Updates the observation with new attributes. Returns the observation for method chaining.
771

772
```typescript
773
observation.update({
774
  output: { result: 'success' },
775
  metadata: { duration: 150 }
776
});
777
```
778

779
### end()
780

781
Marks the observation as complete with optional end timestamp.
782

783
```typescript
784
observation.end(); // Current time
785
observation.end(new Date('2024-01-01T12:00:00Z')); // Custom time
786
```
787

788
### updateTrace()
789

790
Updates the parent trace with trace-level attributes.
791

792
```typescript
793
observation.updateTrace({
794
  userId: 'user-123',
795
  sessionId: 'session-456',
796
  tags: ['production', 'api-v2']
797
});
798
```
799

800
### startObservation()
801

802
Creates a new child observation within this observation's context.
803

804
```typescript
805
const child = observation.startObservation('child-operation', {
806
  input: { step: 'processing' }
807
}, { asType: 'span' });
808
```
809

810
## Choosing the Right Type
811

812
### Decision Tree
813

814
1. **Is it a point-in-time occurrence?** → Use `event`
815
2. **Is it an LLM API call?** → Use `generation`
816
3. **Is it text embedding generation?** → Use `embedding`
817
4. **Is it an AI agent workflow?** → Use `agent`
818
5. **Is it a single tool/API call?** → Use `tool`
819
6. **Is it document retrieval?** → Use `retriever`
820
7. **Is it quality evaluation?** → Use `evaluator`
821
8. **Is it a safety check?** → Use `guardrail`
822
9. **Is it a multi-step workflow?** → Use `chain`
823
10. **Default for general operations** → Use `span`
824

825
### Type Selection Guide
826

827
```typescript
828
// LLM interactions
829
startObservation('openai-call', {}, { asType: 'generation' });
830
startObservation('embed-text', {}, { asType: 'embedding' });
831

832
// Intelligent workflows
833
startObservation('ai-agent', {}, { asType: 'agent' });
834
startObservation('rag-pipeline', {}, { asType: 'chain' });
835

836
// Individual operations
837
startObservation('api-call', {}, { asType: 'tool' });
838
startObservation('vector-search', {}, { asType: 'retriever' });
839

840
// Quality and safety
841
startObservation('evaluate-output', {}, { asType: 'evaluator' });
842
startObservation('content-filter', {}, { asType: 'guardrail' });
843

844
// Events and general ops
845
startObservation('user-action', {}, { asType: 'event' });
846
startObservation('data-processing', {}); // defaults to 'span'
847
```
848