# Langfuse -- Setup & Configuration Examples

> OpenTelemetry initialization, environment config, sampling, data masking, multi-project setup, and lifecycle management. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [tracing.md](tracing.md) -- Tracing with observations, nesting, metadata
- [openai-integration.md](openai-integration.md) -- OpenAI SDK auto-instrumentation
- [prompt-management.md](prompt-management.md) -- Prompt management and versioning
- [scores-datasets.md](scores-datasets.md) -- Scores, datasets, experiments

---

## Basic Setup

```typescript
// instrumentation.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});

sdk.start();

export { sdk };
```

```bash
# .env
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_BASE_URL="https://cloud.langfuse.com"   # EU region
# LANGFUSE_BASE_URL="https://us.cloud.langfuse.com"  # US region
```

```typescript
// index.ts -- instrumentation MUST be imported first
import { sdk } from "./instrumentation";
import { startActiveObservation } from "@langfuse/tracing";

async function main() {
  await startActiveObservation("my-trace", async (span) => {
    span.update({
      input: "Hello, Langfuse!",
      output: "Trace captured successfully.",
    });
  });
}

main().finally(() => sdk.shutdown());
```

---

## Client Initialization

```typescript
// lib/langfuse.ts
import { LangfuseClient } from "@langfuse/client";

// Reads credentials from environment variables automatically
const langfuse = new LangfuseClient();

export { langfuse };
```

```typescript
// lib/langfuse.ts -- explicit configuration
import { LangfuseClient } from "@langfuse/client";

const TIMEOUT_MS = 10_000;

const langfuse = new LangfuseClient({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  baseUrl: process.env.LANGFUSE_BASE_URL,
  timeout: TIMEOUT_MS,
});

export { langfuse };
```

---

## Sampling for High-Volume Applications

```typescript
// instrumentation.ts -- sample 20% of traces
import { NodeSDK } from "@opentelemetry/sdk-node";
import { TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const SAMPLE_RATE = 0.2;

const sdk = new NodeSDK({
  sampler: new TraceIdRatioBasedSampler(SAMPLE_RATE),
  spanProcessors: [new LangfuseSpanProcessor()],
});

sdk.start();

export { sdk };
```

Or via environment variable: `LANGFUSE_SAMPLE_RATE=0.2`

---

## Data Masking

```typescript
// instrumentation.ts -- redact PII before sending to Langfuse
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const CREDIT_CARD_PATTERN = /\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b/g;
const EMAIL_PATTERN = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g;

const processor = new LangfuseSpanProcessor({
  mask: ({ data }) =>
    data
      .replace(CREDIT_CARD_PATTERN, "***MASKED_CC***")
      .replace(EMAIL_PATTERN, "***MASKED_EMAIL***"),
});

const sdk = new NodeSDK({
  spanProcessors: [processor],
});

sdk.start();

export { sdk };
```

---

## Span Filtering

```typescript
// instrumentation.ts -- only export Langfuse + custom spans
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor, isDefaultExportSpan } from "@langfuse/otel";

const processor = new LangfuseSpanProcessor({
  shouldExportSpan: ({ otelSpan }) =>
    isDefaultExportSpan(otelSpan) ||
    otelSpan.instrumentationScope.name.startsWith("my-app"),
});

const sdk = new NodeSDK({
  spanProcessors: [processor],
});

sdk.start();

export { sdk };
```

---

## Isolated TracerProvider

Separate Langfuse tracing from other observability backends:

```typescript
// instrumentation.ts -- isolated provider
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { setLangfuseTracerProvider } from "@langfuse/tracing";

const langfuseProvider = new NodeTracerProvider({
  spanProcessors: [new LangfuseSpanProcessor()],
});

setLangfuseTracerProvider(langfuseProvider);
```

---

## Multi-Project Setup

```typescript
// instrumentation.ts -- send spans to multiple Langfuse projects
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

const sdk = new NodeSDK({
  spanProcessors: [
    new LangfuseSpanProcessor({
      publicKey: "pk-lf-project-1",
      secretKey: "sk-lf-project-1",
    }),
    new LangfuseSpanProcessor({
      publicKey: "pk-lf-project-2",
      secretKey: "sk-lf-project-2",
    }),
  ],
});

sdk.start();

export { sdk };
```

---

## Debug Logging

```bash
# Via environment variable
LANGFUSE_LOG_LEVEL=DEBUG

# Or via code
```

```typescript
import { configureGlobalLogger } from "@langfuse/core";

configureGlobalLogger({ level: "DEBUG" });
```

---

## Serverless / Short-Lived Process Pattern

For serverless environments, use `exportMode: "immediate"` on the span processor to export spans immediately rather than batching:

```typescript
// instrumentation.ts (serverless variant)
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseSpanProcessor } from "@langfuse/otel";

export const langfuseSpanProcessor = new LangfuseSpanProcessor({
  exportMode: "immediate",
});

export const sdk = new NodeSDK({
  spanProcessors: [langfuseSpanProcessor],
});

sdk.start();
```

```typescript
import { sdk } from "./instrumentation";
import { startActiveObservation } from "@langfuse/tracing";
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

export async function handler(event: unknown) {
  try {
    return await startActiveObservation("lambda-handler", async (span) => {
      span.update({ input: event });
      const result = await processEvent(event);
      span.update({ output: result });

      // Score the result
      langfuse.score.activeTrace({
        name: "success",
        value: 1,
        dataType: "BOOLEAN",
      });

      return result;
    });
  } finally {
    // CRITICAL: flush before Lambda freezes
    await langfuse.score.flush();
    await sdk.shutdown();
  }
}
```

---

_For tracing patterns, see [tracing.md](tracing.md). For API reference, see [reference.md](../reference.md)._

# Langfuse -- OpenAI Integration Examples

> Auto-instrumentation with `observeOpenAI()`, streaming token tracking, custom attributes, and nested tracing. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Setup, environment config, flush/shutdown
- [tracing.md](tracing.md) -- Manual tracing patterns
- [prompt-management.md](prompt-management.md) -- Prompt management
- [scores-datasets.md](scores-datasets.md) -- Scores and datasets

---

## Basic OpenAI Wrapper

```typescript
// lib/openai.ts
import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";

// Wrap the OpenAI client -- all calls automatically traced
const openai = observeOpenAI(new OpenAI());

export { openai };
```

```typescript
// usage.ts
import { openai } from "./lib/openai";

const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "developer", content: "You are a helpful assistant." },
    { role: "user", content: "Explain async/await in TypeScript." },
  ],
});

console.log(completion.choices[0].message.content);
// Langfuse automatically captures: model, tokens, cost, latency
```

---

## Custom Trace Attributes

Pass metadata to control how the generation appears in Langfuse.

```typescript
import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";

const openai = observeOpenAI(new OpenAI(), {
  generationName: "intent-classifier",
  sessionId: "session-abc-123",
  userId: "user-456",
  tags: ["production", "classifier-v2"],
  generationMetadata: {
    feature: "intent-classification",
    version: "2.1",
  },
});

const result = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "I want to book a flight" }],
});
```

---

## Streaming with Token Tracking

For streaming calls, set `stream_options.include_usage` to capture token counts.

```typescript
import { openai } from "./lib/openai";

const stream = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Tell me a story." }],
  stream: true,
  stream_options: { include_usage: true }, // REQUIRED for token tracking on streams
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}
// Token usage automatically captured by observeOpenAI
```

**Without `stream_options: { include_usage: true }`**, OpenAI does not return token counts for streaming responses, and Langfuse will show `null` for token usage.

---

## Nested Inside Manual Traces

Combine `observeOpenAI` with manual tracing for richer context.

```typescript
import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";
import { startActiveObservation } from "@langfuse/tracing";

const openai = observeOpenAI(new OpenAI());

async function summarizeArticle(article: string): Promise<string> {
  return await startActiveObservation("summarize-article", async (span) => {
    span.update({ input: { articleLength: article.length } });

    // OpenAI call is automatically a child of "summarize-article"
    const completion = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [
        {
          role: "developer",
          content: "Summarize the following article concisely.",
        },
        { role: "user", content: article },
      ],
    });

    const summary = completion.choices[0].message.content ?? "";
    span.update({ output: { summary, summaryLength: summary.length } });
    return summary;
  });
}
```

---

## Multi-Step Pipeline with OpenAI

```typescript
import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";
import { startActiveObservation, propagateAttributes } from "@langfuse/tracing";

const openai = observeOpenAI(new OpenAI());

async function chatPipeline(
  userId: string,
  sessionId: string,
  message: string,
): Promise<string> {
  return await propagateAttributes(
    { userId, sessionId, tags: ["chat-v3"] },
    async () => {
      return await startActiveObservation("chat-pipeline", async (rootSpan) => {
        rootSpan.update({ input: { message } });

        // Step 1: Classify intent
        const intentResult = await startActiveObservation(
          "classify-intent",
          async () => {
            const completion = await openai.chat.completions.create({
              model: "gpt-4o",
              messages: [
                {
                  role: "developer",
                  content:
                    "Classify the user intent as: question, command, or greeting.",
                },
                { role: "user", content: message },
              ],
              temperature: 0,
            });
            return completion.choices[0].message.content ?? "unknown";
          },
          { asType: "agent" },
        );

        // Step 2: Generate response based on intent
        const response = await startActiveObservation(
          "generate-response",
          async () => {
            const completion = await openai.chat.completions.create({
              model: "gpt-4o",
              messages: [
                {
                  role: "developer",
                  content: `User intent: ${intentResult}. Respond appropriately.`,
                },
                { role: "user", content: message },
              ],
            });
            return completion.choices[0].message.content ?? "";
          },
          { asType: "generation" },
        );

        rootSpan.update({ output: { intent: intentResult, response } });
        return response;
      });
    },
  );
}
```

---

## Limitations

- `observeOpenAI()` does **NOT** support the OpenAI Assistants API (server-side state is incompatible)
- Requires OpenAI SDK version >= 4.0.0
- Requires OTel `NodeSDK` to be initialized before using the wrapper
- Token counts on streaming calls require explicit `stream_options: { include_usage: true }`

---

_For tracing patterns, see [tracing.md](tracing.md). For setup, see [core.md](core.md)._

# Langfuse -- Prompt Management Examples

> Fetching prompts, compiling variables, text vs chat prompts, versioning, labels, caching, and linking prompts to traces. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Setup, environment config, flush/shutdown
- [tracing.md](tracing.md) -- Manual tracing patterns
- [openai-integration.md](openai-integration.md) -- OpenAI auto-instrumentation
- [scores-datasets.md](scores-datasets.md) -- Scores and datasets

---

## Fetching and Compiling Text Prompts

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Fetch a text prompt (production label by default)
const prompt = await langfuse.prompt.get("summarize-article");

// Compile with variables -- replaces {{variable}} placeholders
const compiled = prompt.compile({
  topic: "climate change",
  length: "200 words",
});
// -> "Write a 200 words summary about climate change."

// Use compiled prompt with your LLM
const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "developer", content: compiled },
    { role: "user", content: articleText },
  ],
});
```

---

## Chat Prompts

Chat prompts return an array of message objects ready for LLM APIs.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Fetch a chat prompt
const chatPrompt = await langfuse.prompt.get("customer-support", {
  type: "chat",
});

// Compile with variables
const messages = chatPrompt.compile({
  userName: "Alice",
  productName: "Pro Plan",
});
// -> [
//   { role: "system", content: "You are helping Alice with their Pro Plan." },
//   { role: "user", content: "{{user_message}}" }
// ]

// Use directly with OpenAI
const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    ...messages,
    { role: "user", content: "How do I cancel my subscription?" },
  ],
});
```

---

## Prompt Versioning and Labels

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Default: fetches "production" label
const prodPrompt = await langfuse.prompt.get("classifier");

// Fetch a specific label (for A/B testing or staging)
const stagingPrompt = await langfuse.prompt.get("classifier", {
  label: "staging",
});

// Fetch a specific version number
const v2Prompt = await langfuse.prompt.get("classifier", {
  version: 2,
});
```

---

## Cache Control

The SDK caches prompts by default. Control caching behavior for development or frequently updated prompts.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Bypass cache -- always fetch from server
const freshPrompt = await langfuse.prompt.get("classifier", {
  cacheTtlSeconds: 0,
});

// Custom cache TTL (in seconds)
const CACHE_TTL_SECONDS = 300;
const cachedPrompt = await langfuse.prompt.get("classifier", {
  cacheTtlSeconds: CACHE_TTL_SECONDS,
});
```

**Note:** When a cached prompt expires, the SDK returns the stale prompt immediately while refreshing in the background. This prevents latency spikes from cache misses.

---

## Creating Prompts Programmatically

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Create a text prompt
await langfuse.prompt.create({
  name: "summarize-article",
  prompt: "Write a {{length}} summary about {{topic}}. Focus on key facts.",
  type: "text",
});

// Create a chat prompt
await langfuse.prompt.create({
  name: "customer-support",
  prompt: [
    {
      role: "system",
      content: "You are a support agent helping {{userName}}.",
    },
    { role: "user", content: "{{user_message}}" },
  ],
  type: "chat",
});
```

---

## Linking Prompts to Traces

When using `observeOpenAI`, pass the `langfusePrompt` option to link a prompt version to the generation trace.

```typescript
import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();
const openai = observeOpenAI(new OpenAI());

async function classifyWithManagedPrompt(text: string): Promise<string> {
  const prompt = await langfuse.prompt.get("classifier");
  const compiled = prompt.compile({ text });

  // Link prompt version to the trace for tracking
  const trackedOpenai = observeOpenAI(new OpenAI(), {
    langfusePrompt: prompt,
    generationName: "classify-text",
  });

  const completion = await trackedOpenai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: compiled }],
  });

  return completion.choices[0].message.content ?? "";
}
```

---

## Prompt with Fallback

For guaranteed availability, provide a fallback prompt in case the Langfuse API is unreachable.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

const FALLBACK_PROMPT = "Summarize the following text concisely: {{text}}";

const prompt = await langfuse.prompt.get("summarizer", {
  fallback: FALLBACK_PROMPT,
});

// If Langfuse API is down, compile() uses the fallback template
const compiled = prompt.compile({ text: articleContent });
```

---

_For tracing patterns, see [tracing.md](tracing.md). For setup, see [core.md](core.md)._

# Langfuse -- Scores & Datasets Examples

> Creating scores (numeric, categorical, boolean), attaching to traces/observations, datasets, experiments, and evaluation workflows. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Setup, environment config, flush/shutdown
- [tracing.md](tracing.md) -- Manual tracing patterns
- [openai-integration.md](openai-integration.md) -- OpenAI auto-instrumentation
- [prompt-management.md](prompt-management.md) -- Prompt management

---

## Score Types

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Numeric score (float value)
langfuse.score.create({
  traceId: "trace-abc-123",
  name: "relevance",
  value: 0.92,
  dataType: "NUMERIC",
});

// Categorical score (string value)
langfuse.score.create({
  traceId: "trace-abc-123",
  name: "tone",
  value: "professional",
  dataType: "CATEGORICAL",
});

// Boolean score (0 or 1 as float, NOT true/false)
langfuse.score.create({
  traceId: "trace-abc-123",
  name: "contains-pii",
  value: 0,
  dataType: "BOOLEAN",
});
```

**Note:** Boolean scores use `0` (false) or `1` (true) as float values, not JavaScript `true`/`false`.

---

## Scoring Specific Observations

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Score a specific generation within a trace
langfuse.score.create({
  traceId: "trace-abc-123",
  observationId: "obs-def-456",
  name: "accuracy",
  value: 0.88,
  dataType: "NUMERIC",
});
```

---

## Scoring Active Observations

Score the currently active OTel span without needing trace/observation IDs.

```typescript
import { startActiveObservation } from "@langfuse/tracing";
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

await startActiveObservation("process-query", async (span) => {
  span.update({ input: { query: "What is AI?" } });

  const result = await processQuery("What is AI?");

  // Score the active observation (this span)
  langfuse.score.activeObservation({
    name: "quality",
    value: 0.95,
    dataType: "NUMERIC",
  });

  // Score the active trace (root trace)
  langfuse.score.activeTrace({
    name: "user-satisfaction",
    value: "satisfied",
    dataType: "CATEGORICAL",
  });

  span.update({ output: { result } });
});

// Flush in short-lived processes
await langfuse.score.flush();
```

---

## User Feedback Scores

Capture user feedback (thumbs up/down, ratings) as scores.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// User thumbs up/down
function handleFeedback(traceId: string, isPositive: boolean) {
  langfuse.score.create({
    traceId,
    name: "user-feedback",
    value: isPositive ? 1 : 0,
    dataType: "BOOLEAN",
    comment: isPositive
      ? "User liked the response"
      : "User disliked the response",
  });
}

// User star rating (1-5)
function handleRating(traceId: string, rating: number) {
  langfuse.score.create({
    traceId,
    name: "user-rating",
    value: rating,
    dataType: "NUMERIC",
  });
}
```

---

## Session-Level Scores

Score an entire session (multiple traces).

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Score a session
langfuse.score.create({
  sessionId: "session-xyz-789",
  name: "session-quality",
  value: "excellent",
  dataType: "CATEGORICAL",
});
```

---

## Creating Datasets

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Create a dataset
await langfuse.api.datasets.create({
  name: "qa-benchmark",
  description: "Question-answer pairs for regression testing",
  metadata: {
    author: "Alice",
    created: "2025-10-01",
    type: "benchmark",
  },
});

// Add items to the dataset
await langfuse.api.datasetItems.create({
  datasetName: "qa-benchmark",
  input: {
    question: "What is the capital of France?",
  },
  expectedOutput: {
    answer: "Paris",
  },
  metadata: {
    difficulty: "easy",
    category: "geography",
  },
});

await langfuse.api.datasetItems.create({
  datasetName: "qa-benchmark",
  input: {
    question: "Explain quantum entanglement in simple terms.",
  },
  expectedOutput: {
    answer:
      "Quantum entanglement is when two particles are connected so that measuring one instantly affects the other, regardless of distance.",
  },
  metadata: {
    difficulty: "hard",
    category: "physics",
  },
});
```

---

## Running Experiments

Run your LLM function against a dataset and collect results.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Get the dataset
const dataset = await langfuse.dataset.get("qa-benchmark");

// Run experiment with a task function
const result = await dataset.runExperiment({
  name: "gpt-4o-baseline-v1",
  description: "Baseline experiment with gpt-4o",
  task: async ({ item }) => {
    // Your LLM function
    const completion = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [
        { role: "developer", content: "Answer the question accurately." },
        { role: "user", content: item.input.question },
      ],
    });
    return completion.choices[0].message.content;
  },
});

console.log(`Experiment: ${result.runName}`);
console.log(`Results: ${result.itemResults.length} items processed`);
console.log(`URL: ${result.datasetRunUrl}`);
```

---

## Experiments with Evaluators

Add evaluators to automatically score experiment results.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

const dataset = await langfuse.dataset.get("qa-benchmark");

const result = await dataset.runExperiment({
  name: "gpt-4o-with-eval",
  task: async ({ item }) => {
    const completion = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: item.input.question }],
    });
    return completion.choices[0].message.content;
  },
  evaluators: [
    // Per-item evaluator
    async ({ input, output, expectedOutput }) => {
      const isCorrect = output
        ?.toLowerCase()
        .includes(expectedOutput?.answer?.toLowerCase() ?? "");
      return {
        name: "contains-answer",
        value: isCorrect ? 1 : 0,
        dataType: "BOOLEAN" as const,
      };
    },
  ],
});
```

---

## Linking Dataset Items to Production Traces

Connect dataset items to real production traces for context.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Link a dataset item to a source trace
await langfuse.api.datasetItems.create({
  datasetName: "qa-benchmark",
  input: { question: "What is the capital of France?" },
  expectedOutput: { answer: "Paris" },
  sourceTraceId: "trace-from-production-123",
  sourceObservationId: "obs-456",
});
```

---

## Versioned Datasets

Run experiments against specific dataset snapshots.

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Get dataset at a specific version timestamp
const versionTimestamp = new Date("2025-12-15T06:30:00").toISOString();
const versionedDataset = await langfuse.dataset.get("qa-benchmark", {
  version: versionTimestamp,
});

const result = await versionedDataset.runExperiment({
  name: "baseline-on-v1",
  description: "Running against December 2025 snapshot",
  task: async ({ item }) => {
    return await myLLMFunction(item.input);
  },
});
```

---

## Archiving Dataset Items

```typescript
import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Archive a dataset item by ID
await langfuse.api.datasetItems.create({
  id: "item-abc-123",
  status: "ARCHIVED",
});
```

---

_For tracing patterns, see [tracing.md](tracing.md). For setup, see [core.md](core.md)._

# Langfuse -- Tracing Examples

> Observation creation, nesting, context propagation, observation types, metadata, sessions, and user tracking. See [SKILL.md](../SKILL.md) for core patterns.

**Related examples:**

- [core.md](core.md) -- Setup, environment config, flush/shutdown
- [openai-integration.md](openai-integration.md) -- OpenAI auto-instrumentation
- [prompt-management.md](prompt-management.md) -- Prompt management
- [scores-datasets.md](scores-datasets.md) -- Scores and datasets

---

## startActiveObservation -- Context Manager

The primary tracing method. Creates an observation, sets it as active context, and ends it automatically.

```typescript
import { startActiveObservation } from "@langfuse/tracing";

async function handleChatMessage(message: string): Promise<string> {
  return await startActiveObservation("chat-handler", async (span) => {
    span.update({ input: { message } });

    const intent = await classifyIntent(message);
    const response = await generateResponse(intent, message);

    span.update({ output: { response, intent } });
    return response;
  });
}
```

---

## Nested Observations

Child observations automatically inherit parent context when created during the parent's active scope.

```typescript
import { startActiveObservation } from "@langfuse/tracing";

async function ragPipeline(query: string): Promise<string> {
  return await startActiveObservation("rag-pipeline", async (rootSpan) => {
    rootSpan.update({ input: { query } });

    // Child 1: Retrieve documents (typed as retriever)
    const docs = await startActiveObservation(
      "retrieve-docs",
      async (span) => {
        span.update({ input: { query } });
        const results = await vectorStore.search(query);
        span.update({ output: { documentCount: results.length } });
        return results;
      },
      { asType: "retriever" },
    );

    // Child 2: Generate answer (typed as generation)
    const answer = await startActiveObservation(
      "generate-answer",
      async (span) => {
        span.update({
          input: { query, contextDocs: docs.length },
          model: "gpt-4o",
        });
        const result = await callLLM(query, docs);
        span.update({ output: { answer: result } });
        return result;
      },
      { asType: "generation" },
    );

    rootSpan.update({ output: { answer } });
    return answer;
  });
}
```

---

## observe() Function Wrapper

Wraps functions for declarative tracing. Inputs and outputs are captured automatically.

```typescript
import { observe } from "@langfuse/tracing";

const classifyIntent = observe(
  async (query: string): Promise<string> => {
    const completion = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [
        { role: "system", content: "Classify the user intent." },
        { role: "user", content: query },
      ],
    });
    return completion.choices[0].message.content ?? "unknown";
  },
  { name: "classify-intent", asType: "generation" },
);

const searchDocuments = observe(
  async (query: string): Promise<Document[]> => {
    return await vectorStore.similaritySearch(query);
  },
  { name: "search-documents", asType: "retriever" },
);

// Usage -- both functions are automatically traced
const intent = await classifyIntent("Book a flight to Paris");
const docs = await searchDocuments("Paris flights availability");
```

### Controlling Input/Output Capture

```typescript
// Disable input capture (for sensitive data)
const secureFn = observe(
  async (sensitiveInput: string) => {
    /* ... */
  },
  { name: "secure-fn", captureInput: false },
);

// Disable output capture
const largeFn = observe(
  async (input: string) => {
    /* returns large object */
  },
  { name: "large-fn", captureOutput: false },
);
```

---

## Manual Observations with startObservation

For cases where you need explicit control over observation lifecycle.

```typescript
import { startObservation } from "@langfuse/tracing";

async function processItem(item: WorkItem): Promise<void> {
  const span = startObservation(
    "process-item",
    { input: { itemId: item.id } },
    { asType: "tool" },
  );

  try {
    const result = await performWork(item);
    span.update({ output: { result } });
  } catch (error) {
    span.update({
      output: {
        error: error instanceof Error ? error.message : "Unknown error",
      },
    });
    throw error;
  } finally {
    span.end(); // REQUIRED -- must explicitly end
  }
}
```

---

## Token Usage on Manual Generations

When manually creating generation observations (not using `observeOpenAI`), report token counts via `usageDetails`:

```typescript
import { startObservation } from "@langfuse/tracing";

const generation = startObservation(
  "llm-call",
  {
    model: "gpt-4o",
    input: [{ role: "user", content: "What is the capital of France?" }],
  },
  { asType: "generation" },
);

// ... perform LLM call ...

generation.update({
  output: { content: "The capital of France is Paris." },
  usageDetails: {
    input: 10,
    output: 5,
    total: 15,
  },
});

generation.end();
```

**Note:** `total` is automatically calculated if omitted. You can also add custom token metrics (e.g., `cache_read_input_tokens`).

---

## Observation Types

Use `asType` to give semantic meaning to observations.

```typescript
import { startActiveObservation } from "@langfuse/tracing";

// Agent step -- decision-making
await startActiveObservation(
  "plan-next-action",
  async (span) => {
    span.update({ input: { state: currentState } });
    const action = await agent.decide(currentState);
    span.update({ output: { action } });
  },
  { asType: "agent" },
);

// Tool call -- external API
await startActiveObservation(
  "call-weather-api",
  async (span) => {
    span.update({ input: { location: "Paris" } });
    const weather = await weatherAPI.get("Paris");
    span.update({ output: weather });
  },
  { asType: "tool" },
);

// Retriever -- vector search
await startActiveObservation(
  "vector-search",
  async (span) => {
    span.update({ input: { query: "climate change" } });
    const docs = await vectorStore.search("climate change");
    span.update({ output: { count: docs.length } });
  },
  { asType: "retriever" },
);

// Evaluator -- quality check
await startActiveObservation(
  "check-relevance",
  async (span) => {
    span.update({ input: { answer, query } });
    const score = await evaluateRelevance(answer, query);
    span.update({ output: { score } });
  },
  { asType: "evaluator" },
);

// Embedding call
await startActiveObservation(
  "create-embedding",
  async (span) => {
    span.update({
      input: { text: "Hello world" },
      model: "text-embedding-3-small",
    });
    const embedding = await createEmbedding("Hello world");
    span.update({ output: { dimensions: embedding.length } });
  },
  { asType: "embedding" },
);
```

---

## User and Session Tracking

Use `propagateAttributes()` to attach user, session, and metadata to all nested observations. It wraps a callback -- all observations created inside the callback inherit the attributes.

```typescript
import { startActiveObservation, propagateAttributes } from "@langfuse/tracing";

async function handleUserRequest(
  userId: string,
  sessionId: string,
  query: string,
) {
  return await propagateAttributes(
    {
      userId,
      sessionId,
      tags: ["production", "v2"],
      metadata: { environment: "prod", region: "eu-west-1" },
    },
    async () => {
      return await startActiveObservation("user-request", async (span) => {
        span.update({ input: { query } });
        const result = await processQuery(query);
        span.update({ output: { result } });
        return result;
      });
    },
  );
}
```

---

## Updating Active Observation Without Reference

```typescript
import {
  startActiveObservation,
  updateActiveObservation,
} from "@langfuse/tracing";

async function deeplyNestedFunction() {
  // Update the currently active observation from anywhere in the call stack
  updateActiveObservation({
    metadata: { step: "validation", validated: true },
  });
}

await startActiveObservation("outer", async () => {
  await deeplyNestedFunction(); // Updates "outer" observation's metadata
});
```

---

## Trace and Span ID Access

```typescript
import {
  startActiveObservation,
  getActiveTraceId,
  getActiveSpanId,
  createTraceId,
} from "@langfuse/tracing";

await startActiveObservation("my-trace", async () => {
  const traceId = getActiveTraceId();
  const spanId = getActiveSpanId();
  console.log(`Trace: ${traceId}, Span: ${spanId}`);
});

// Deterministic trace ID for correlation with external systems
const traceId = createTraceId("order-12345");
```

---

## Time to First Token (TTFT) Tracking

```typescript
import { startActiveObservation } from "@langfuse/tracing";

await startActiveObservation(
  "llm-call",
  async (span) => {
    span.update({ input: { prompt: "Tell me a story" }, model: "gpt-4o" });

    let firstTokenReceived = false;
    const stream = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Tell me a story" }],
      stream: true,
    });

    for await (const chunk of stream) {
      if (!firstTokenReceived) {
        span.update({ completionStartTime: new Date().toISOString() });
        firstTokenReceived = true;
      }
      // Process chunk...
    }
  },
  { asType: "generation" },
);
```

---

## Cross-Service Context Propagation

Use `asBaggage: true` to propagate context across HTTP boundaries via W3C Baggage headers.

```typescript
import { propagateAttributes } from "@langfuse/tracing";

// In the upstream service -- wraps a callback
await propagateAttributes(
  { userId: "user-123", sessionId: "session-456" },
  async () => {
    // All observations created here inherit userId and sessionId
    await handleRequest();
  },
  { asBaggage: true }, // Propagates via HTTP headers
);
```

---

_For setup and configuration, see [core.md](core.md). For API reference, see [reference.md](../reference.md)._