0
# @langfuse/tracing
1

2
OpenTelemetry-based instrumentation methods for observability and tracing of LLM (Large Language Model) applications. This package provides comprehensive functions and decorators for creating and managing observations with automatic lifecycle management, supporting multiple observation types including spans, generations, agents, tools, chains, retrievers, evaluators, guardrails, embeddings, and events, with full TypeScript type safety and automatic type inference.
3

4
## Package Information
5

6
- **Package Name**: @langfuse/tracing
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @langfuse/tracing @opentelemetry/api`
10
- **Peer Dependencies**: `@opentelemetry/api@^1.9.0`
11
- **Minimum Node Version**: 20+
12

13
## Core Imports
14

15
```typescript
16
import {
17
  startObservation,
18
  startActiveObservation,
19
  observe,
20
  updateActiveTrace,
21
  updateActiveObservation,
22
  getActiveTraceId,
23
  getActiveSpanId,
24
  createTraceId,
25
  createTraceAttributes,
26
  createObservationAttributes,
27
  setLangfuseTracerProvider,
28
  getLangfuseTracerProvider,
29
  getLangfuseTracer
30
} from '@langfuse/tracing';
31
```
32

33
Type imports:
34

35
```typescript
36
import type {
37
  // Core observation types
38
  LangfuseObservationType,
39
  ObservationLevel,
40

41
  // Attribute types
42
  LangfuseSpanAttributes,
43
  LangfuseEventAttributes,
44
  LangfuseGenerationAttributes,
45
  LangfuseObservationAttributes,
46
  LangfuseTraceAttributes,
47

48
  // Option types
49
  StartObservationOptions,
50
  StartActiveObservationContext,
51
  StartObservationOpts,
52
  StartActiveObservationOpts,
53
  ObserveOptions,
54

55
  // Context types
56
  TraceContext,
57

58
  // Observation class types
59
  LangfuseObservation,
60
  LangfuseSpan,
61
  LangfuseGeneration,
62
  LangfuseEvent,
63
  LangfuseAgent,
64
  LangfuseTool,
65
  LangfuseChain,
66
  LangfuseRetriever,
67
  LangfuseEvaluator,
68
  LangfuseGuardrail,
69
  LangfuseEmbedding,
70

71
  // OpenTelemetry constants
72
  LangfuseOtelSpanAttributes
73
} from '@langfuse/tracing';
74
```
75

76
**Note:** Observation-specific attribute types (`LangfuseAgentAttributes`, `LangfuseToolAttributes`, etc.) are not exported from the package. Instead, use `LangfuseSpanAttributes` for span-based observations (agent, tool, chain, retriever, evaluator, guardrail, event) or `LangfuseGenerationAttributes` for generation-based observations (embedding). These specialized types are type aliases internally but are not part of the public API.
77

78
For CommonJS:
79

80
```javascript
81
const {
82
  startObservation,
83
  startActiveObservation,
84
  observe
85
} = require('@langfuse/tracing');
86
```
87

88
## Basic Usage
89

90
```typescript
91
import { startObservation, startActiveObservation } from '@langfuse/tracing';
92

93
// Manual lifecycle management
94
const span = startObservation('data-processing', {
95
  input: { userId: '123', dataSize: 1024 },
96
  metadata: { processor: 'fast-lane' }
97
});
98

99
try {
100
  const result = await processData();
101
  span.update({ output: { processed: true, records: result.count } });
102
} finally {
103
  span.end();
104
}
105

106
// Automatic lifecycle management
107
const response = await startActiveObservation(
108
  'llm-call',
109
  async (generation) => {
110
    generation.update({
111
      input: [{ role: 'user', content: 'Explain AI' }],
112
      model: 'gpt-4',
113
      modelParameters: { temperature: 0.7 }
114
    });
115

116
    const result = await openai.chat.completions.create({
117
      model: 'gpt-4',
118
      messages: [{ role: 'user', content: 'Explain AI' }]
119
    });
120

121
    generation.update({
122
      output: result.choices[0].message,
123
      usageDetails: {
124
        promptTokens: result.usage.prompt_tokens,
125
        completionTokens: result.usage.completion_tokens
126
      }
127
    });
128

129
    return result.choices[0].message.content;
130
  },
131
  { asType: 'generation' }
132
);
133

134
// Zero-code-change function wrapping
135
const processOrder = observe(
136
  async (orderId: string, items: CartItem[]) => {
137
    const validation = await validateOrder(orderId, items);
138
    const payment = await processPayment(validation);
139
    return { orderId, status: 'confirmed' };
140
  },
141
  {
142
    name: 'process-order',
143
    asType: 'span',
144
    captureInput: true,
145
    captureOutput: true
146
  }
147
);
148
```
149

150
## Architecture
151

152
The @langfuse/tracing package is built around several key components:
153

154
- **Observation Types**: 10 specialized observation types (span, generation, event, agent, tool, chain, retriever, evaluator, guardrail, embedding) for different AI workflow scenarios
155
- **Instrumentation Methods**: Three complementary approaches for adding observability:
156
  - `startObservation()` for manual lifecycle control
157
  - `startActiveObservation()` for function-scoped automatic management
158
  - `observe()` decorator for wrapping existing functions
159
- **OpenTelemetry Integration**: Built on OpenTelemetry API with custom span attributes and processors
160
- **Type Safety**: Full TypeScript support with automatic type inference based on observation type
161
- **Lifecycle Management**: Automatic or manual observation start/end with promise support
162
- **Context Propagation**: Leverages OpenTelemetry context for parent-child relationships
163

164
## Capabilities
165

166
### Manual Observation Lifecycle
167

168
Create observations with explicit control over start and end timing. Ideal for complex workflows requiring precise timing control or long-running operations.
169

170
```typescript { .api }
171
function startObservation(
172
  name: string,
173
  attributes?: LangfuseObservationAttributes,
174
  options?: StartObservationOpts
175
): LangfuseObservation;
176

177
type StartObservationOpts = {
178
  asType?: LangfuseObservationType;
179
  startTime?: Date;
180
  parentSpanContext?: SpanContext;
181
};
182
```
183

184
[Manual Observation Lifecycle](./manual-observations.md)
185

186
### Automatic Observation Lifecycle
187

188
Execute functions within observation contexts with automatic lifecycle management, context propagation, and error handling. Perfect for function-scoped operations.
189

190
```typescript { .api }
191
function startActiveObservation<F extends (observation: LangfuseObservation) => unknown>(
192
  name: string,
193
  fn: F,
194
  options?: StartActiveObservationOpts
195
): ReturnType<F>;
196

197
type StartActiveObservationOpts = {
198
  asType?: LangfuseObservationType;
199
  startTime?: Date;
200
  parentSpanContext?: SpanContext;
201
  endOnExit?: boolean;
202
};
203
```
204

205
[Automatic Observation Lifecycle](./active-observations.md)
206

207
### Function Decoration
208

209
Wrap existing functions with observability without modifying their implementation. Zero-code-change instrumentation for any function.
210

211
```typescript { .api }
212
function observe<T extends (...args: any[]) => any>(
213
  fn: T,
214
  options?: ObserveOptions
215
): T;
216

217
interface ObserveOptions {
218
  name?: string;
219
  asType?: LangfuseObservationType;
220
  captureInput?: boolean;
221
  captureOutput?: boolean;
222
  parentSpanContext?: SpanContext;
223
  endOnExit?: boolean;
224
}
225
```
226

227
[Function Decoration](./observe-decorator.md)
228

229
### Observation Types
230

231
Ten specialized observation types for different AI workflow scenarios: spans for general operations, generations for LLM calls, agents for autonomous workflows, tools for API calls, chains for multi-step pipelines, retrievers for document search, evaluators for quality assessment, guardrails for safety checks, embeddings for vector operations, and events for point-in-time logging.
232

233
```typescript { .api }
234
type LangfuseObservationType =
235
  | "span"
236
  | "generation"
237
  | "event"
238
  | "agent"
239
  | "tool"
240
  | "chain"
241
  | "retriever"
242
  | "evaluator"
243
  | "guardrail"
244
  | "embedding";
245
```
246

247
[Observation Types](./observation-types.md)
248

249
### Context Management
250

251
Access and update the currently active trace and observation contexts from anywhere in your code execution flow.
252

253
```typescript { .api }
254
function updateActiveTrace(attributes: LangfuseTraceAttributes): void;
255

256
function updateActiveObservation(
257
  attributes: LangfuseObservationAttributes,
258
  options?: { asType?: LangfuseObservationType }
259
): void;
260

261
function getActiveTraceId(): string | undefined;
262

263
function getActiveSpanId(): string | undefined;
264
```
265

266
[Context Management](./context-management.md)
267

268
### Tracer Provider Configuration
269

270
Configure custom OpenTelemetry tracer providers for isolated or customized tracing setups, enabling integration with existing OpenTelemetry infrastructure.
271

272
```typescript { .api }
273
function setLangfuseTracerProvider(provider: TracerProvider | null): void;
274

275
function getLangfuseTracerProvider(): TracerProvider;
276

277
function getLangfuseTracer(): Tracer;
278
```
279

280
[Tracer Provider Configuration](./tracer-provider.md)
281

282
### Trace ID Generation
283

284
Create deterministic or random trace IDs for custom trace correlation and external system integration.
285

286
```typescript { .api }
287
async function createTraceId(seed?: string): Promise<string>;
288
```
289

290
[Trace ID Generation](./trace-id-generation.md)
291

292
### Attribute Creation
293

294
Low-level functions for creating OpenTelemetry attributes from Langfuse-specific attribute types. Typically used internally but available for advanced use cases.
295

296
```typescript { .api }
297
function createTraceAttributes(attributes?: LangfuseTraceAttributes): Attributes;
298

299
function createObservationAttributes(
300
  type: LangfuseObservationType,
301
  attributes: LangfuseObservationAttributes
302
): Attributes;
303
```
304

305
[Attribute Creation](./attribute-creation.md)
306

307
### OpenTelemetry Span Attribute Constants
308

309
Enum of OpenTelemetry attribute key constants used by Langfuse for trace and observation attributes. Primarily used internally but exported for advanced use cases requiring direct OpenTelemetry span manipulation.
310

311
```typescript { .api }
312
enum LangfuseOtelSpanAttributes {
313
  // Trace attributes
314
  TRACE_NAME = "langfuse.trace.name",
315
  TRACE_USER_ID = "user.id",
316
  TRACE_SESSION_ID = "session.id",
317

318
  // Observation attributes
319
  OBSERVATION_TYPE = "langfuse.observation.type",
320
  OBSERVATION_INPUT = "langfuse.observation.input",
321
  OBSERVATION_OUTPUT = "langfuse.observation.output",
322

323
  // ... and more (see full documentation)
324
}
325
```
326

327
[OpenTelemetry Span Attributes](./otel-span-attributes.md)
328

329
## Common Types
330

331
### Observation Attributes
332

333
```typescript { .api }
334
type LangfuseSpanAttributes = {
335
  input?: unknown;
336
  output?: unknown;
337
  metadata?: Record<string, unknown>;
338
  level?: ObservationLevel;
339
  statusMessage?: string;
340
  version?: string;
341
  environment?: string;
342
};
343

344
type ObservationLevel = "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
345

346
type LangfuseGenerationAttributes = LangfuseSpanAttributes & {
347
  completionStartTime?: Date;
348
  model?: string;
349
  modelParameters?: { [key: string]: string | number };
350
  usageDetails?: { [key: string]: number };
351
  costDetails?: { [key: string]: number };
352
  prompt?: {
353
    name: string;
354
    version: number;
355
    isFallback: boolean;
356
  };
357
};
358
```
359

360
### Trace Attributes
361

362
```typescript { .api }
363
type LangfuseTraceAttributes = {
364
  name?: string;
365
  userId?: string;
366
  sessionId?: string;
367
  version?: string;
368
  release?: string;
369
  input?: unknown;
370
  output?: unknown;
371
  metadata?: unknown;
372
  tags?: string[];
373
  public?: boolean;
374
  environment?: string;
375
};
376
```
377

378
### Observation Union Type
379

380
```typescript { .api }
381
type LangfuseObservation =
382
  | LangfuseSpan
383
  | LangfuseGeneration
384
  | LangfuseEvent
385
  | LangfuseAgent
386
  | LangfuseTool
387
  | LangfuseChain
388
  | LangfuseRetriever
389
  | LangfuseEvaluator
390
  | LangfuseGuardrail
391
  | LangfuseEmbedding;
392
```
393

394
### Trace Context
395

396
Context information for linking observations to traces, used internally for maintaining parent-child relationships between observations.
397

398
```typescript { .api }
399
type TraceContext = {
400
  /** The trace ID that observations should be linked to */
401
  traceId: string;
402
  /** Optional parent observation ID for creating hierarchical relationships */
403
  parentObservationId?: string;
404
};
405
```
406

407
### Observation Attribute Type Aliases
408

409
The following observation types use specialized attribute structures:
410

411
**Span-based observations** (all extend `LangfuseSpanAttributes`):
412
```typescript { .api }
413
type LangfuseEventAttributes = LangfuseSpanAttributes;
414
type LangfuseAgentAttributes = LangfuseSpanAttributes;
415
type LangfuseToolAttributes = LangfuseSpanAttributes;
416
type LangfuseChainAttributes = LangfuseSpanAttributes;
417
type LangfuseRetrieverAttributes = LangfuseSpanAttributes;
418
type LangfuseEvaluatorAttributes = LangfuseSpanAttributes;
419
type LangfuseGuardrailAttributes = LangfuseSpanAttributes;
420
```
421

422
**Generation-based observations** (extend `LangfuseGenerationAttributes`):
423
```typescript { .api }
424
type LangfuseEmbeddingAttributes = LangfuseGenerationAttributes;
425
```
426

427
These type aliases provide semantic clarity while inheriting all properties from their base types. When using observation-specific types (agent, tool, chain, etc.), you have access to all the same attributes as `LangfuseSpanAttributes` (input, output, metadata, level, statusMessage, version, environment).
428