0
# Langfuse
1

2
Langfuse is a comprehensive observability and analytics platform for LLM applications. It provides automatic tracing, prompt management, dataset operations, and integrations with popular LLM providers like OpenAI. The SDK supports Node.js (>=18), Web browsers, and Edge runtimes with full TypeScript support.
3

4
## Package Information
5

6
- **Package Name**: langfuse
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Version**: 3.38.5
10
- **Installation**: `npm install langfuse`
11
- **Node Version**: >= 18
12
- **License**: MIT
13

14
## Core Imports
15

16
```typescript
17
import { Langfuse, LangfuseWeb } from 'langfuse';
18
```
19

20
For CommonJS:
21

22
```javascript
23
const { Langfuse, LangfuseWeb } = require('langfuse');
24
```
25

26
## Basic Usage
27

28
```typescript
29
import { Langfuse } from 'langfuse';
30

31
// Initialize the client
32
const langfuse = new Langfuse({
33
  publicKey: 'your-public-key',
34
  secretKey: 'your-secret-key',
35
  baseUrl: 'https://cloud.langfuse.com' // optional
36
});
37

38
// Create a trace
39
const trace = langfuse.trace({
40
  name: 'my-application',
41
  userId: 'user-123',
42
  metadata: { environment: 'production' }
43
});
44

45
// Add a generation (LLM call)
46
const generation = trace.generation({
47
  name: 'chat-completion',
48
  model: 'gpt-4',
49
  input: [{ role: 'user', content: 'Hello!' }],
50
  output: { role: 'assistant', content: 'Hi there!' },
51
  usage: { input: 10, output: 15, total: 25 }
52
});
53

54
// Flush events to Langfuse
55
await langfuse.flushAsync();
56
```
57

58
## Architecture
59

60
Langfuse is built around several key components:
61

62
- **Hierarchical Tracing**: Traces contain spans, generations, and events that can be nested to represent complex execution flows
63
- **Client Objects**: Chainable API with dedicated client classes (LangfuseTraceClient, LangfuseSpanClient, etc.) for fluent trace composition
64
- **Automatic Batching**: Events are queued and sent in batches for efficient network usage with configurable flush intervals
65
- **Prompt Management**: Caching system with TTL and background refresh for prompt templates with support for text and chat prompts
66
- **Media Handling**: Automatic detection and upload of media content (images, PDFs, etc.) with reference strings for efficient storage
67
- **Dataset Operations**: Complete dataset management for evaluations, experiments, and testing workflows
68
- **Multi-Environment**: Single codebase supporting Node.js, Web browsers, Deno, and Edge runtimes
69

70
## Capabilities
71

72
### Core Tracing
73

74
Create and manage hierarchical traces for observability. Traces can contain nested spans, generations (LLM calls), and events.
75

76
```typescript { .api }
77
class Langfuse {
78
  /**
79
   * Creates a new trace
80
   * @param body - Optional trace configuration
81
   * @returns Trace client for chaining operations
82
   */
83
  trace(body?: CreateLangfuseTraceBody): LangfuseTraceClient;
84

85
  /**
86
   * Creates a span observation
87
   * @param body - Span configuration with traceId
88
   * @returns Span client for chaining operations
89
   */
90
  span(body: CreateLangfuseSpanBody): LangfuseSpanClient;
91

92
  /**
93
   * Creates a generation observation (LLM call)
94
   * @param body - Generation configuration
95
   * @returns Generation client for chaining operations
96
   */
97
  generation(body: Omit<CreateLangfuseGenerationBody, "promptName" | "promptVersion"> & PromptInput): LangfuseGenerationClient;
98

99
  /**
100
   * Creates an event observation
101
   * @param body - Event configuration
102
   * @returns Event client for chaining operations
103
   */
104
  event(body: CreateLangfuseEventBody): LangfuseEventClient;
105

106
  /**
107
   * Creates a score for a trace or observation
108
   * @param body - Score configuration
109
   * @returns Langfuse instance for chaining
110
   */
111
  score(body: CreateLangfuseScoreBody): this;
112
}
113
```
114

115
[Tracing](./tracing.md)
116

117
### Prompt Management
118

119
Fetch and manage prompts with automatic caching, versioning, and support for both text and chat formats.
120

121
```typescript { .api }
122
class Langfuse {
123
  /**
124
   * Fetches a text prompt with caching support
125
   * @param name - Prompt name
126
   * @param version - Optional version (defaults to latest production)
127
   * @param options - Optional cache TTL configuration
128
   * @returns Text prompt client
129
   */
130
  getPrompt(name: string, version?: number, options?: GetPromptOptions): Promise<TextPromptClient>;
131

132
  /**
133
   * Fetches a chat prompt with caching support
134
   * @param name - Prompt name
135
   * @param version - Optional version (defaults to latest production)
136
   * @param options - Chat-specific configuration
137
   * @returns Chat prompt client
138
   */
139
  getPrompt(name: string, version?: number, options?: GetPromptOptionsChat): Promise<ChatPromptClient>;
140

141
  /**
142
   * Creates a new text prompt
143
   * @param body - Text prompt configuration
144
   * @returns Text prompt client
145
   */
146
  createPrompt(body: CreateTextPromptBody): Promise<TextPromptClient>;
147

148
  /**
149
   * Creates a new chat prompt
150
   * @param body - Chat prompt configuration
151
   * @returns Chat prompt client
152
   */
153
  createPrompt(body: CreateChatPromptBody | CreateChatPromptBodyWithPlaceholders): Promise<ChatPromptClient>;
154
}
155
```
156

157
[Prompt Management](./prompts.md)
158

159
### Dataset Operations
160

161
Create and manage datasets for evaluations, experiments, and testing. Link observations to dataset items for run tracking.
162

163
```typescript { .api }
164
class Langfuse {
165
  /**
166
   * Fetches a dataset with all its items
167
   * @param name - Dataset name
168
   * @param options - Optional pagination settings
169
   * @returns Dataset with items
170
   */
171
  getDataset(name: string, options?: { fetchItemsPageSize: number }): Promise<Dataset>;
172

173
  /**
174
   * Creates a new dataset
175
   * @param body - Dataset configuration
176
   * @returns Dataset creation response
177
   */
178
  createDataset(body: CreateLangfuseDatasetBody): Promise<CreateLangfuseDatasetResponse>;
179

180
  /**
181
   * Creates a dataset item
182
   * @param body - Dataset item configuration
183
   * @returns Dataset item response
184
   */
185
  createDatasetItem(body: CreateLangfuseDatasetItemBody): Promise<CreateLangfuseDatasetItemResponse>;
186

187
  /**
188
   * Links an observation to a dataset item for run tracking
189
   * @param body - Run item configuration
190
   * @returns Run item response
191
   */
192
  createDatasetRunItem(body: CreateLangfuseDatasetRunItemBody): Promise<CreateLangfuseDatasetRunItemResponse>;
193
}
194
```
195

196
[Dataset Operations](./datasets.md)
197

198
### OpenAI Integration
199

200
Automatic tracing for OpenAI SDK calls with minimal code changes using a proxy wrapper.
201

202
```typescript { .api }
203
/**
204
 * Wraps an OpenAI SDK instance with automatic Langfuse tracing
205
 * @param sdk - The OpenAI SDK instance to wrap
206
 * @param langfuseConfig - Optional tracing configuration
207
 * @returns Wrapped SDK with tracing and flush methods
208
 */
209
function observeOpenAI<SDKType extends object>(
210
  sdk: SDKType,
211
  langfuseConfig?: LangfuseConfig
212
): SDKType & LangfuseExtension;
213

214
interface LangfuseExtension {
215
  /** Flushes all pending Langfuse events */
216
  flushAsync(): Promise<void>;
217
  /** Shuts down the Langfuse client */
218
  shutdownAsync(): Promise<void>;
219
}
220
```
221

222
[OpenAI Integration](./openai-integration.md)
223

224
### Media Handling
225

226
Automatic handling of media content (images, PDFs, etc.) with cloud storage upload and reference strings.
227

228
```typescript { .api }
229
class LangfuseMedia {
230
  /**
231
   * Creates a media object for upload
232
   * @param params - Media source (base64, file path, bytes, or object)
233
   */
234
  constructor(params: {
235
    obj?: object;
236
    base64DataUri?: string;
237
    contentType?: MediaContentType;
238
    contentBytes?: Buffer;
239
    filePath?: string;
240
  });
241

242
  /**
243
   * Returns a media reference string for storage
244
   * @returns Reference string in format @@@langfuseMedia:type={...}|id={...}@@@
245
   */
246
  toJSON(): string | undefined;
247

248
  /**
249
   * Resolves media references in an object to base64 data URIs
250
   * @param params - Object with references and resolution settings
251
   * @returns Object with resolved media content
252
   */
253
  static resolveMediaReferences<T>(
254
    params: LangfuseMediaResolveMediaReferencesParams<T>
255
  ): Promise<T>;
256
}
257
```
258

259
[Media Handling](./media.md)
260

261
### Public API Access
262

263
Direct access to Langfuse REST API endpoints for advanced operations.
264

265
```typescript { .api }
266
class Langfuse {
267
  /** Public API client for direct API access */
268
  api: LangfusePublicApi<null>["api"];
269
}
270
```
271

272
The `api` property provides access to all REST API endpoints including traces, observations, sessions, datasets, prompts, scores, and more.
273

274
[Public API](./public-api.md)
275

276
### Configuration
277

278
Comprehensive configuration options for customizing Langfuse behavior.
279

280
```typescript { .api }
281
class Langfuse {
282
  constructor(params?: {
283
    publicKey?: string;
284
    secretKey?: string;
285
  } & LangfuseOptions);
286
}
287

288
interface LangfuseOptions {
289
  /** Persistence strategy: localStorage, sessionStorage, cookie, or memory */
290
  persistence?: "localStorage" | "sessionStorage" | "cookie" | "memory";
291
  /** Custom name for persistence storage */
292
  persistence_name?: string;
293
  /** Enable/disable tracing */
294
  enabled?: boolean;
295
  /** Base URL for Langfuse API */
296
  baseUrl?: string;
297
  /** Number of events before auto-flush (default: 15) */
298
  flushAt?: number;
299
  /** Flush interval in milliseconds (default: 10000) */
300
  flushInterval?: number;
301
  /** Request timeout in milliseconds (default: 5000) */
302
  requestTimeout?: number;
303
  /** Release version identifier */
304
  release?: string;
305
  /** Environment name */
306
  environment?: string;
307
  /** Function to mask sensitive data */
308
  mask?: MaskFunction;
309
  /** Sampling rate (0-1) */
310
  sampleRate?: number;
311
  /** Number of retries for failed requests (default: 3) */
312
  fetchRetryCount?: number;
313
  /** Retry delay in milliseconds (default: 3000) */
314
  fetchRetryDelay?: number;
315
  /** SDK integration identifier */
316
  sdkIntegration?: string;
317
  /** Additional HTTP headers */
318
  additionalHeaders?: Record<string, string>;
319
}
320
```
321

322
[Configuration](./configuration.md)
323

324
### Lifecycle Management
325

326
Methods for managing the client lifecycle and event flushing.
327

328
```typescript { .api }
329
class Langfuse {
330
  /**
331
   * Flushes all pending events asynchronously
332
   * @returns Promise that resolves when all events are sent
333
   */
334
  flushAsync(): Promise<void>;
335

336
  /**
337
   * Shuts down the client, flushing all pending events
338
   * @returns Promise that resolves when shutdown is complete
339
   */
340
  shutdownAsync(): Promise<void>;
341

342
  /**
343
   * Registers an event listener
344
   * @param event - Event name
345
   * @param cb - Callback function
346
   * @returns Unsubscribe function
347
   */
348
  on(event: string, cb: (...args: any[]) => void): () => void;
349

350
  /**
351
   * Enables or disables debug mode
352
   * @param enabled - Debug mode state (default: true)
353
   */
354
  debug(enabled?: boolean): void;
355

356
  /**
357
   * @deprecated Use flushAsync() instead. This method does not wait for events to be sent.
358
   * Flushes pending events synchronously with optional callback
359
   * @param callback - Optional callback function
360
   */
361
  flush(callback?: (err?: any, data?: any) => void): void;
362

363
  /**
364
   * @deprecated Use shutdownAsync() instead. This method does not wait for events to be processed.
365
   * Shuts down the client synchronously
366
   */
367
  shutdown(): void;
368
}
369
```
370

371
### Fetching Traces and Observations
372

373
Retrieve existing traces, observations, and sessions for analysis.
374

375
```typescript { .api }
376
class Langfuse {
377
  /**
378
   * Fetches traces with optional filtering
379
   * @param query - Filter and pagination options
380
   * @returns Paginated traces response
381
   */
382
  fetchTraces(query?: GetLangfuseTracesQuery): Promise<GetLangfuseTracesResponse>;
383

384
  /**
385
   * Fetches a specific trace by ID
386
   * @param traceId - Trace identifier
387
   * @returns Trace with full details
388
   */
389
  fetchTrace(traceId: string): Promise<{ data: GetLangfuseTraceResponse }>;
390

391
  /**
392
   * Fetches observations with optional filtering
393
   * @param query - Filter and pagination options
394
   * @returns Paginated observations response
395
   */
396
  fetchObservations(query?: GetLangfuseObservationsQuery): Promise<GetLangfuseObservationsResponse>;
397

398
  /**
399
   * Fetches a specific observation by ID
400
   * @param observationId - Observation identifier
401
   * @returns Observation details
402
   */
403
  fetchObservation(observationId: string): Promise<{ data: GetLangfuseObservationResponse }>;
404

405
  /**
406
   * Fetches sessions with optional filtering
407
   * @param query - Filter and pagination options
408
   * @returns Paginated sessions response
409
   */
410
  fetchSessions(query?: GetLangfuseSessionsQuery): Promise<GetLangfuseSessionsResponse>;
411
}
412
```
413

414
### Web-Only Client
415

416
Stateless client for browser environments using only a public key.
417

418
```typescript { .api }
419
class LangfuseWeb {
420
  /**
421
   * Creates a web-only Langfuse client
422
   * @param params - Configuration without secretKey
423
   */
424
  constructor(params?: Omit<LangfuseOptions, "secretKey">);
425

426
  /**
427
   * Creates a score and flushes immediately
428
   * @param body - Score configuration
429
   * @returns Promise resolving to LangfuseWeb instance
430
   */
431
  score(body: CreateLangfuseScoreBody): Promise<this>;
432
}
433
```
434

435
LangfuseWeb uses stateless tracing where events are sent immediately without batching. It's designed for client-side tracking and does not require a secret key.
436

437
## Internal Utilities (Not Exported)
438

439
**Note**: The `langfuse-core` package contains internal utility functions, but these are not exported from the main `langfuse` package and should not be used directly by consumers. All necessary functionality is exposed through the public API classes documented above.
440

441
## Advanced Types
442

443
### LangfuseMemoryStorage
444

445
In-memory storage implementation for environments that don't support localStorage/sessionStorage.
446

447
```typescript { .api }
448
class LangfuseMemoryStorage {
449
  /**
450
   * Gets a stored property value
451
   * @param key - Property key
452
   * @returns Stored value or undefined
453
   */
454
  getProperty(key: LangfusePersistedProperty): any | undefined;
455

456
  /**
457
   * Sets a property value in memory
458
   * @param key - Property key
459
   * @param value - Value to store (null to clear)
460
   */
461
  setProperty(key: LangfusePersistedProperty, value: any | null): void;
462
}
463

464
enum LangfusePersistedProperty {
465
  /** Queue persistence key */
466
  Queue = "queue"
467
}
468
```
469

470
This class is automatically used in environments without persistent storage (e.g., server-side Node.js). You typically don't need to interact with it directly.
471