Complete Langfuse integration skill pack with 24 skills covering LLM observability, tracing, prompt management, and evaluation. Flagship tier vendor pack.

24 Skills

MIT License

Free Pricing

Installation

Open Claude Code and run this command:

/plugin install langfuse-pack@claude-code-plugins-plus

Use --global to install for all projects, or --project for current project only.

Skills (24)

langfuse-ci-integration SKILL.md View full skill →

Configure Langfuse CI/CD integration with GitHub Actions and automated testing.

ReadWriteEditBash(gh:*)

Langfuse CI Integration

Overview

Integrate Langfuse into CI/CD pipelines: trace validation tests, prompt regression testing, experiment-driven quality gates, automated prompt deployment from version control, and score monitoring.

Prerequisites

Langfuse API keys stored as GitHub secrets (LANGFUSEPUBLICKEY, LANGFUSESECRETKEY)
Test framework (Vitest or Jest)
OpenAI API key for LLM tests

Instructions

Step 1: GitHub Actions Workflow for AI Quality Tests


# .github/workflows/langfuse-tests.yml
name: AI Quality Tests

on:
  pull_request:
    paths: ["src/ai/**", "src/prompts/**", "tests/ai/**"]

jobs:
  ai-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: "20", cache: "npm" }
      - run: npm ci

      - name: Run AI quality tests with tracing
        env:
          LANGFUSE_PUBLIC_KEY: ${{ secrets.LANGFUSE_PUBLIC_KEY }}
          LANGFUSE_SECRET_KEY: ${{ secrets.LANGFUSE_SECRET_KEY }}
          LANGFUSE_BASE_URL: ${{ vars.LANGFUSE_BASE_URL || 'https://cloud.langfuse.com' }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: npx vitest run tests/ai/ --reporter=verbose

      - name: Langfuse connectivity check
        env:
          LANGFUSE_PUBLIC_KEY: ${{ secrets.LANGFUSE_PUBLIC_KEY }}
          LANGFUSE_SECRET_KEY: ${{ secrets.LANGFUSE_SECRET_KEY }}
        run: |
          node -e "
            const { LangfuseClient } = require('@langfuse/client');
            const lf = new LangfuseClient();
            lf.prompt.get('__ci-health__').catch(() => {});
            console.log('Langfuse SDK initialized OK');
          "

Step 2: Prompt Regression Tests


// tests/ai/prompt-quality.test.ts
import { describe, it, expect, afterAll } from "vitest";
import { LangfuseClient } from "@langfuse/client";
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";
import OpenAI from "openai";

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

describe("Prompt Quality Regression", () => {
  it("summarization prompt produces valid output", async () => {
    const prompt = await langfuse.prompt.get("summarize-article", { type: "text" });
    const compiled = prompt.compile({ maxLength: "100 words" });

    const result = await startActiveObservation(
      { name: "ci-test-summarize", asType: "generation" },
      async () => {
        updateActiveObservation({ model: "gpt-4o-mini", input: compiled });

        const response = await openai.chat.completions.create({


                
                  
                  
                  langfuse-common-errors
                  SKILL.md
                  View full skill →
                
                
                  Diagnose and fix common Langfuse errors and exceptions.
                  
                      ReadGrepBash(curl:*)
                    
                
                
                  Langfuse Common Errors
Overview
Diagnostic reference for the 10 most common Langfuse integration errors, with real error messages, root causes, and tested solutions.
Prerequisites

Langfuse SDK installed
API credentials configured
Access to application logs or console output

Error Reference
1. Authentication Failed (401)
Error:

Langfuse: Unauthorized - Invalid API key
Error: 401 Unauthorized

Cause: API key missing, expired, revoked, or keys from wrong project.
Fix:

set -euo pipefail
# Verify env vars are set
echo "Public: ${LANGFUSE_PUBLIC_KEY:0:15}..."
echo "Secret: ${LANGFUSE_SECRET_KEY:0:10}..."

# Test auth against API
HOST="${LANGFUSE_BASE_URL:-https://cloud.langfuse.com}"
curl -s -o /dev/null -w "HTTP %{http_code}" \
  "$HOST/api/public/health"

# Auth test
curl -s -o /dev/null -w "HTTP %{http_code}" \
  -H "Authorization: Basic $(echo -n "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" | base64)" \
  "$HOST/api/public/traces?limit=1"

2. Traces Not Appearing in Dashboard
Symptom: Code runs without errors but no traces show in UI.
Root causes (in order of likelihood):

Data not flushed before process exits
Wrong project keys (traces going to different project)
Dashboard filter hiding traces

Fix:

// v4+: Ensure OTel SDK is shut down properly
const sdk = new NodeSDK({ spanProcessors: [new LangfuseSpanProcessor()] });
sdk.start();
// ... your code ...
await sdk.shutdown(); // MUST call this before process exits

// v3: Always flush
await langfuse.flushAsync();

// v3: Register shutdown handler for long-running processes
process.on("beforeExit", async () => {
  await langfuse.shutdownAsync();
});

3. Network / Connection Errors
Error:

FetchError: request to https://cloud.langfuse.com failed
ECONNREFUSED / ETIMEDOUT

Fix:

set -euo pipefail
# Test connectivity
curl -v https://cloud.langfuse.com/api/public/health

# Check DNS
nslookup cloud.langfuse.com

# For self-hosted
curl -v $LANGFUSE_BASE_URL/api/public/health


// Increase timeout for slow networks
// v4+: Configure via OTel span processor options
// v3:
const langfuse = new Langfuse({ requestTimeout: 30000 });

4. Missing Token Usage
Symptom: Generations appear but token counts show zero.
Fix:

// For OpenAI streaming -- enable usage reporting
const


                
                  
                  
                  langfuse-core-workflow-a
                  SKILL.md
                  View full skill →
                
                
                  Execute Langfuse primary workflow: Tracing LLM calls and spans.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Langfuse Core Workflow A: Tracing LLM Calls
Overview
End-to-end tracing of LLM calls, chains, and agents. Covers the OpenAI drop-in wrapper, manual tracing with startActiveObservation, RAG pipeline instrumentation, streaming response tracking, and LangChain integration.
Prerequisites

Completed langfuse-install-auth setup
OpenAI SDK installed (npm install openai)
For v4+: @langfuse/openai, @langfuse/tracing, @langfuse/otel, @opentelemetry/sdk-node

Instructions
Step 1: OpenAI Drop-In Wrapper (Zero-Code Tracing)

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

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

// Every call captures: model, input, output, tokens, latency, cost
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is Langfuse?" },
  ],
});

// Add metadata to traces
const res = await observeOpenAI(new OpenAI(), {
  generationName: "product-description",
  generationMetadata: { feature: "onboarding" },
  sessionId: "session-abc",
  userId: "user-123",
  tags: ["production", "onboarding"],
}).chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Describe this product" }],
});

Step 2: Manual Tracing -- RAG Pipeline (v4+ SDK)

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

async function ragPipeline(query: string) {
  return await startActiveObservation("rag-pipeline", async () => {
    updateActiveObservation({ input: { query }, metadata: { pipeline: "rag-v2" } });

    // Span: Query embedding
    const embedding = await startActiveObservation("embed-query", async () => {
      updateActiveObservation({ input: { text: query } });
      const vector = await embedText(query);
      updateActiveObservation({
        output: { dimensions: vector.length },
        metadata: { model: "text-embedding-3-small" },
      });
      return vector;
    });

    // Span: Vector search
    const documents = await startActiveObservation("vector-search", async () => {
      updateActiveObservation({ input: { dimensions: embedding.length } });
      const docs = await searchVectorDB(embedding);
      updateActiveObservation({
        output: { documentCount: docs.length, topScore: docs[0]?.score },
      });
      return docs;
    });

    // Generation: LLM call w


                
                  
                  
                  langfuse-core-workflow-b
                  SKILL.md
                  View full skill →
                
                
                  Execute Langfuse secondary workflow: Evaluation, scoring, and datasets.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Langfuse Core Workflow B: Evaluation, Scoring & Datasets
Overview
Implement LLM output evaluation using Langfuse scores (numeric, categorical, boolean), the experiment runner SDK for dataset-driven benchmarks, prompt management with versioned prompts, and LLM-as-a-Judge evaluation patterns.
Prerequisites

Langfuse SDK configured with API keys
Traces already being collected (see langfuse-core-workflow-a)
For v4+: @langfuse/client installed

Instructions
Step 1: Score Traces via SDK
Langfuse supports three score data types: Numeric, Categorical, and Boolean.

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

const langfuse = new LangfuseClient();

// Numeric score (e.g., 0-1 quality rating)
await langfuse.score.create({
  traceId: "trace-abc-123",
  name: "relevance",
  value: 0.92,
  dataType: "NUMERIC",
  comment: "Highly relevant answer with good context usage",
});

// Categorical score (e.g., pass/fail classification)
await langfuse.score.create({
  traceId: "trace-abc-123",
  observationId: "gen-xyz-456", // Optional: score a specific generation
  name: "quality-tier",
  value: "excellent",
  dataType: "CATEGORICAL",
});

// Boolean score (e.g., thumbs up/down)
await langfuse.score.create({
  traceId: "trace-abc-123",
  name: "user-approved",
  value: 1, // 1 = true, 0 = false
  dataType: "BOOLEAN",
  comment: "User clicked thumbs up",
});

Step 2: User Feedback Collection

// API endpoint for frontend feedback widget
app.post("/api/feedback", async (req, res) => {
  const { traceId, rating, comment } = req.body;

  // Thumbs up/down
  await langfuse.score.create({
    traceId,
    name: "user-feedback",
    value: rating === "positive" ? 1 : 0,
    dataType: "BOOLEAN",
    comment,
  });

  // Granular star rating (1-5)
  if (req.body.stars) {
    await langfuse.score.create({
      traceId,
      name: "star-rating",
      value: req.body.stars,
      dataType: "NUMERIC",
      comment: `${req.body.stars}/5 stars`,
    });
  }

  res.json({ success: true });
});

Step 3: Prompt Management

// Fetch a versioned prompt from Langfuse
const textPrompt = await langfuse.prompt.get("summarize-article", {
  type: "text",
  label: "production", // or "latest", "staging"
});

// Compile with variables -- replaces {{variable}} placeholders
const compiled = textPrompt.compile({
  maxLength: "100 words",
  tone: "professional",
});

// Chat prompts return message arrays
c


                
                  
                  
                  langfuse-cost-tuning
                  SKILL.md
                  View full skill →
                
                
                  Monitor and optimize LLM costs using Langfuse analytics and dashboards.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Cost Tuning
Overview
Track, analyze, and optimize LLM costs using Langfuse's built-in token/cost tracking, the Metrics API for programmatic cost analysis, model routing for cost reduction, and automated budget alerts.
Prerequisites

Langfuse tracing with token usage captured (via observeOpenAI or manual usage fields)
For Metrics API: @langfuse/client installed
Understanding of LLM pricing models

How Langfuse Tracks Costs
Langfuse automatically calculates costs for supported models (OpenAI, Anthropic, Google) when token usage is captured. For custom models, you can configure pricing in the Langfuse UI under Settings > Model Definitions.
Cost tracking works on observations of type generation and embedding. The observeOpenAI wrapper captures usage automatically; for manual tracing, include usage in your observation updates.
Instructions
Step 1: Ensure Token Usage is Captured

// Automatic: observeOpenAI captures everything
import { observeOpenAI } from "@langfuse/openai";
const openai = observeOpenAI(new OpenAI());
// Tokens, model, latency, and cost are all auto-tracked

// Manual: include usage in generation observations
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";

await startActiveObservation(
  { name: "llm-call", asType: "generation" },
  async () => {
    updateActiveObservation({ model: "gpt-4o" }); // Model required for cost calc

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

    updateActiveObservation({
      output: response.choices[0].message.content,
      usage: {
        promptTokens: response.usage?.prompt_tokens,
        completionTokens: response.usage?.completion_tokens,
        totalTokens: response.usage?.total_tokens,
      },
      // Optional: override inferred cost (in USD)
      // costInUsd: 0.0015,
    });
  }
);

Step 2: Query Costs via Metrics API

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

const langfuse = new LangfuseClient();

// Fetch aggregated cost metrics
async function getCostReport(days: number) {
  const fromTimestamp = new Date(Date.now() - days * 86400000).toISOString();

  // Use the API to list traces with cost data
  const traces = await langfuse.api.traces.list({
    fromTimestamp,
    limit: 1000,
    orderBy: "timestamp",
  });

  const costByModel = new Map<string, { cost: number; tokens: number; count: number }>();

  for (const trace of traces.data) {
    const observations = await langfuse.api.observations.list({
      traceId: trace.


                
                  
                  
                  langfuse-data-handling
                  SKILL.md
                  View full skill →
                
                
                  Manage Langfuse data export, retention, and compliance requirements.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Data Handling
Overview
Manage the Langfuse data lifecycle: export traces and scores via the API, configure retention policies, handle GDPR data subject requests, anonymize data for analytics, and maintain audit trails.
Prerequisites

@langfuse/client installed
Langfuse API keys with appropriate permissions
Understanding of your compliance requirements (GDPR, SOC2, HIPAA)

Instructions
Step 1: Export Trace Data via API

import { LangfuseClient } from "@langfuse/client";
import { writeFileSync } from "fs";

const langfuse = new LangfuseClient();

async function exportTraces(options: {
  fromDate: string;
  toDate: string;
  outputFile: string;
  includeObservations?: boolean;
}) {
  const allTraces: any[] = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await langfuse.api.traces.list({
      fromTimestamp: options.fromDate,
      toTimestamp: options.toDate,
      limit: 100,
      page,
    });

    for (const trace of result.data) {
      const exportItem: any = {
        id: trace.id,
        name: trace.name,
        timestamp: trace.timestamp,
        userId: trace.userId,
        sessionId: trace.sessionId,
        metadata: trace.metadata,
        tags: trace.tags,
      };

      if (options.includeObservations) {
        const observations = await langfuse.api.observations.list({
          traceId: trace.id,
        });
        exportItem.observations = observations.data;
      }

      allTraces.push(exportItem);
    }

    hasMore = result.data.length === 100;
    page++;

    // Rate limit respect
    await new Promise((r) => setTimeout(r, 200));
  }

  writeFileSync(options.outputFile, JSON.stringify(allTraces, null, 2));
  console.log(`Exported ${allTraces.length} traces to ${options.outputFile}`);
}

// Usage
await exportTraces({
  fromDate: "2025-01-01T00:00:00Z",
  toDate: "2025-01-31T23:59:59Z",
  outputFile: "traces-january.json",
  includeObservations: true,
});

Step 2: Export Scores

async function exportScores(fromDate: string, outputFile: string) {
  const scores: any[] = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const result = await langfuse.api.scores.list({
      fromTimestamp: fromDate,
      limit: 100,
      page,
    });

    scores.push(...result.data);
    hasMore = result.data.length === 100;
    page++;
    await new Promise((r) => setTimeout(r, 200));
  }

  writeFileSync(outputFile, JSON.stringify(scores, null, 2));
  console.log(`Exported ${scores.length} scores to ${outputFile}`);
}

Step 3: Data Retention Configuration
Self-hosted: Set retention via environment variable:

# docker-compose.yml
services:
  langfuse:
    environm


                
                  
                  
                  langfuse-debug-bundle
                  SKILL.md
                  View full skill →
                
                
                  Collect Langfuse debug evidence for support tickets and troubleshooting.
                  
                      ReadBash(grep:*)Bash(curl:*)Bash(tar:*)Grep
                    
                
                
                  Langfuse Debug Bundle
Current State
!node --version 2>/dev/null || echo 'N/A'
!python3 --version 2>/dev/null || echo 'N/A'
!npm list langfuse @langfuse/client @langfuse/tracing 2>/dev/null | head -5 || echo 'No langfuse packages'
Overview
Collect all diagnostic information needed for Langfuse support tickets: environment versions, SDK config, API connectivity, redacted logs, and a reproduction template.
Prerequisites

Langfuse SDK installed
Access to application logs
Bash shell available

Instructions
Step 1: Run the Full Debug Bundle Script
Save this as langfuse-debug.sh and run it:

#!/bin/bash
set -euo pipefail

BUNDLE_DIR="langfuse-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Langfuse Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date)" | tee -a "$BUNDLE_DIR/summary.txt"

# --- Environment ---
{
  echo ""
  echo "--- Environment ---"
  echo "Node.js: $(node --version 2>/dev/null || echo 'not installed')"
  echo "Python: $(python3 --version 2>/dev/null || echo 'not installed')"
  echo "npm: $(npm --version 2>/dev/null || echo 'not installed')"
  echo "OS: $(uname -srm)"
} >> "$BUNDLE_DIR/summary.txt"

# --- SDK Versions ---
{
  echo ""
  echo "--- SDK Versions ---"
  npm list langfuse @langfuse/client @langfuse/tracing @langfuse/otel @langfuse/openai @langfuse/langchain 2>/dev/null || echo "npm: no langfuse packages"
  pip show langfuse 2>/dev/null | grep -E "Name|Version" || echo "pip: langfuse not found"
} >> "$BUNDLE_DIR/summary.txt"

# --- Config (redacted) ---
{
  echo ""
  echo "--- Langfuse Config ---"
  echo "LANGFUSE_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY:+SET (${LANGFUSE_PUBLIC_KEY:0:12}...)}"
  echo "LANGFUSE_SECRET_KEY: ${LANGFUSE_SECRET_KEY:+SET}"
  echo "LANGFUSE_BASE_URL: ${LANGFUSE_BASE_URL:-NOT SET}"
  echo "LANGFUSE_HOST: ${LANGFUSE_HOST:-NOT SET}"
} >> "$BUNDLE_DIR/summary.txt"

# --- Network Connectivity ---
{
  echo ""
  echo "--- Network Test ---"
  HOST="${LANGFUSE_BASE_URL:-${LANGFUSE_HOST:-https://cloud.langfuse.com}}"
  echo "Target host: $HOST"
  echo -n "Health endpoint: "
  curl -s -o /dev/null -w "%{http_code} (%{time_total}s)" "$HOST/api/public/health" 2>/dev/null || echo "FAILED"
  echo ""

  if [ -n "${LANGFUSE_PUBLIC_KEY:-}" ] && [ -n "${LANGFUSE_SECRET_KEY:-}" ]; then
    AUTH=$(echo -n "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" |


                
                  
                  
                  langfuse-deploy-integration
                  SKILL.md
                  View full skill →
                
                
                  Deploy Langfuse with your application across different platforms.
                  
                      ReadWriteEditBash(docker:*)Bash(vercel:*)Bash(gcloud:*)
                    
                
                
                  Langfuse Deploy Integration
Overview
Deploy Langfuse LLM observability alongside your application. Covers integrating the SDK for serverless (Vercel/Lambda), Docker, Cloud Run, and self-hosting the Langfuse server itself.
Prerequisites

Langfuse API keys (cloud or self-hosted)
Application using Langfuse SDK
Target platform CLI installed

Instructions
Step 1: Vercel / Next.js Deployment

set -euo pipefail
# Add secrets to Vercel
vercel env add LANGFUSE_PUBLIC_KEY production
vercel env add LANGFUSE_SECRET_KEY production
vercel env add LANGFUSE_BASE_URL production


// app/api/chat/route.ts (Next.js App Router)
import { NextRequest, NextResponse } from "next/server";
import { LangfuseClient } from "@langfuse/client";
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";
import OpenAI from "openai";

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

export async function POST(req: NextRequest) {
  const { messages } = await req.json();

  const response = await startActiveObservation(
    { name: "chat-api", asType: "generation" },
    async () => {
      updateActiveObservation({
        model: "gpt-4o",
        input: messages,
        metadata: { endpoint: "/api/chat" },
      });

      const result = await openai.chat.completions.create({
        model: "gpt-4o",
        messages,
      });

      updateActiveObservation({
        output: result.choices[0].message,
        usage: {
          promptTokens: result.usage?.prompt_tokens,
          completionTokens: result.usage?.completion_tokens,
        },
      });

      return result.choices[0].message;
    }
  );

  return NextResponse.json(response);
}

> Serverless note: Langfuse SDK v4+ uses OTel which handles flushing asynchronously. For v3, always call await langfuse.flushAsync() before the response returns -- serverless functions may freeze after response.
Step 2: AWS Lambda / Serverless

// handler.ts
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";

// Initialize OUTSIDE handler for connection reuse
const sdk = new NodeSDK({
  spanProcessors: [
    new LangfuseSpanProcessor({
      exportIntervalMillis: 1000, // Flush fast in serverless
    }),
  ],
});
sdk.start();

export const handler = async (event: any) => {
  return await startActiveObservation("lambda-handler", async () => {
    updateActiveObservation({ input: event });

    const result = await processRequest(event);

    updateActiveObservation({ ou


                
                  
                  
                  langfuse-enterprise-rbac
                  SKILL.md
                  View full skill →
                
                
                  Configure Langfuse enterprise organization management and access control.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Enterprise RBAC
Overview
Configure enterprise access control for Langfuse: built-in roles and permissions, scoped API keys per service, SSO integration, project-level isolation, and audit logging for compliance.
Prerequisites

Langfuse Cloud (Team/Enterprise plan) or self-hosted instance
Organization admin access
SSO provider (optional, for SAML/OIDC integration)

Langfuse Built-In Roles
Langfuse provides these roles at the project level:

Role
View Traces
Create Traces
Manage Prompts
Manage Members
Manage Billing


Owner
Yes
Yes
Yes
Yes
Yes


Admin
Yes
Yes
Yes
Yes
No


Member
Yes
Yes
Yes
No
No


Viewer
Yes
No
No
No
No


Instructions
Step 1: Organization and Project Structure

Organization: Acme Corp
├── Project: production-chatbot
│   ├── Owner: engineering-lead@acme.com
│   ├── Admin: senior-dev@acme.com
│   ├── Member: developer@acme.com
│   └── API Key: sk-lf-prod-chatbot-...
│
├── Project: staging-chatbot
│   ├── Admin: senior-dev@acme.com
│   ├── Member: developer@acme.com
│   └── API Key: sk-lf-staging-chatbot-...
│
└── Project: analytics-readonly
    ├── Admin: data-lead@acme.com
    ├── Viewer: analyst@acme.com
    └── API Key: sk-lf-analytics-...

Best practice: Separate projects for production, staging, and analytics. Never share API keys across environments.
Step 2: Scoped API Keys
Create API keys with specific purposes and rotate regularly:

// In Langfuse UI: Settings > API Keys > Create
// Each key pair (public + secret) is scoped to one project

// Service-specific keys
// Backend API:     pk-lf-prod-api-...  / sk-lf-prod-api-...
// CI/CD pipeline:  pk-lf-ci-...       / sk-lf-ci-...
// Analytics:       pk-lf-analytics-... / sk-lf-analytics-...

// Validate key scope at startup
function validateApiKeyScope(expectedProject: string) {
  const pk = process.env.LANGFUSE_PUBLIC_KEY || "";

  if (!pk.includes(expectedProject)) {
    console.warn(
      `WARNING: API key may not match expected project: ${expectedProject}`
    );
  }
}

// Key rotation script
async function rotateApiKeys() {
  // 1. Create new key pair in Langfuse UI
  // 2. Deploy new keys to secret manager
  // 3. Wait for all instances to pick up new keys
  // 4. Revoke old key pair in Langfuse UI

  console.log("Key rotation checklist:");
  console.log("1. [ ] New key pair created in Langfuse");
  console.l


                
                  
                  
                  langfuse-hello-world
                  SKILL.md
                  View full skill →
                
                
                  Create a minimal working Langfuse trace example.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Hello World
Overview
Create your first Langfuse trace with real SDK calls. Demonstrates the trace/span/generation hierarchy, the observe wrapper, and the OpenAI drop-in integration.
Prerequisites

Completed langfuse-install-auth setup
Valid API credentials in environment variables
OpenAI API key (for the OpenAI integration example)

Instructions
Step 1: Hello World with v4+ Modular SDK

// hello-langfuse.ts
import { startActiveObservation, observe, updateActiveObservation } from "@langfuse/tracing";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

// Register OpenTelemetry processor (once at startup)
const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
sdk.start();

async function main() {
  // Create a top-level trace with startActiveObservation
  await startActiveObservation("hello-world", async (span) => {
    span.update({
      input: { message: "Hello, Langfuse!" },
      metadata: { source: "hello-world-example" },
    });

    // Nested span -- automatically linked to parent
    await startActiveObservation("process-input", async (child) => {
      child.update({ input: { text: "processing..." } });
      await new Promise((r) => setTimeout(r, 100));
      child.update({ output: { result: "done" } });
    });

    // Nested generation (LLM call tracking)
    await startActiveObservation(
      { name: "llm-response", asType: "generation" },
      async (gen) => {
        gen.update({
          model: "gpt-4o",
          input: [{ role: "user", content: "Say hello" }],
          output: { content: "Hello! How can I help you today?" },
          usage: { promptTokens: 5, completionTokens: 10, totalTokens: 15 },
        });
      }
    );

    span.update({ output: { status: "completed" } });
  });

  // Allow time for the span processor to flush
  await sdk.shutdown();
  console.log("Trace created! Check your Langfuse dashboard.");
}

main().catch(console.error);

Step 2: Hello World with observe Wrapper
The observe wrapper traces existing functions without modifying internals:

import { observe, updateActiveObservation } from "@langfuse/tracing";

// Wrap any async function -- it becomes a traced span
const processQuery = observe(async (query: string) => {
  updateActiveObservation({ input: { query } });

  // Simulate processing
  const result = `Processed: ${query}`;

  updateActiveObservation({ output: { result } });
  return result;
});

// Wrap an LLM call as a generation
const generateAnswer = observe(
  { name: "


                
                  
                  
                  langfuse-incident-runbook
                  SKILL.md
                  View full skill →
                
                
                  Troubleshoot and respond to Langfuse-related incidents and outages.
                  
                      ReadWriteEditBash(curl:*)
                    
                
                
                  Langfuse Incident Runbook
Overview
Step-by-step procedures for Langfuse-related incidents, from initial triage (2 min) through resolution and post-incident review. Your application should work without Langfuse -- these procedures focus on restoring observability.
Severity Classification

Severity
Description
Response Time
Example


P1
Application impacted by tracing
15 min
SDK throwing unhandled errors, blocking requests


P2
Traces not appearing, no app impact
1 hour
Missing observability data


P3
Degraded performance from tracing
4 hours
High latency from flush backlog


P4
Minor issues
24 hours
Occasional missing traces


Instructions
Step 1: Initial Assessment (2 Minutes)

set -euo pipefail
echo "=== Langfuse Incident Triage ==="
echo "Time: $(date -u)"

# 1. Check Langfuse cloud status
echo -n "Status page: "
curl -s -o /dev/null -w "%{http_code}" https://status.langfuse.com || echo "UNREACHABLE"
echo ""

# 2. Test API connectivity
HOST="${LANGFUSE_BASE_URL:-${LANGFUSE_HOST:-https://cloud.langfuse.com}}"
echo -n "API health: "
curl -s -o /dev/null -w "%{http_code} (%{time_total}s)" "$HOST/api/public/health" || echo "FAILED"
echo ""

# 3. Test auth
if [ -n "${LANGFUSE_PUBLIC_KEY:-}" ] && [ -n "${LANGFUSE_SECRET_KEY:-}" ]; then
  AUTH=$(echo -n "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" | base64)
  echo -n "Auth test: "
  curl -s -o /dev/null -w "%{http_code}" \
    -H "Authorization: Basic $AUTH" "$HOST/api/public/traces?limit=1" || echo "FAILED"
  echo ""
fi

# 4. Check app error logs
echo ""
echo "--- Recent errors ---"
grep -i "langfuse\|trace.*error\|flush.*fail" /var/log/app/*.log 2>/dev/null | tail -10 || echo "No log files found"

Step 2: Determine Incident Type and Response

Symptom
Likely Cause
Immediate Action


No traces appearing
SDK not flushing
Check shutdown handlers; set flushAt: 1 temporarily


401 Unauthorized
Key rotation or mismatch
Verify keys match the correct project


429 Too Many Requests
Rate limited
Increase batch size, reduce flush frequency


SDK throwing errors
Unhandled exception
Wrap in try/catch; check SDK version


High request latency
                
              
                
                  
                  
                  langfuse-install-auth
                  SKILL.md
                  View full skill →
                
                
                  Install and configure Langfuse SDK authentication for LLM observability.
                  
                      ReadWriteEditBash(npm:*)Bash(pip:*)Bash(pnpm:*)Grep
                    
                
                
                  Langfuse Install & Auth
Overview
Install the Langfuse SDK and configure authentication for LLM observability. Covers both the legacy langfuse package (v3) and the modern modular SDK (v4+/v5) built on OpenTelemetry.
Prerequisites

Node.js 18+ or Python 3.9+
Package manager (npm, pnpm, or pip)
Langfuse account (cloud at https://cloud.langfuse.com or self-hosted)
Public Key (pk-lf-...) and Secret Key (sk-lf-...) from project settings

Instructions
Step 1: Install SDK
TypeScript/JavaScript (v4+ modular SDK -- recommended):

set -euo pipefail
# Core client for prompt management, datasets, scores
npm install @langfuse/client

# Tracing (observe, startActiveObservation)
npm install @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node

# OpenAI integration (drop-in wrapper)
npm install @langfuse/openai

# LangChain integration
npm install @langfuse/langchain

TypeScript/JavaScript (v3 legacy -- single package):

npm install langfuse

Python:

pip install langfuse

Step 2: Get API Keys

Open Langfuse dashboard (https://cloud.langfuse.com or your self-hosted URL)
Go to Settings > API Keys
Click Create new API key pair
Copy both keys:


Public Key: pk-lf-... (identifies your project)
Secret Key: sk-lf-... (grants write access -- keep secret)


Note the host URL (cloud default: https://cloud.langfuse.com)

Step 3: Configure Environment Variables

# Set environment variables
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"

# Or create .env file
cat >> .env << 'EOF'
LANGFUSE_PUBLIC_KEY=pk-lf-your-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-secret-key
LANGFUSE_BASE_URL=https://cloud.langfuse.com
EOF

> Note: v4+ uses LANGFUSEBASEURL. Legacy v3 uses LANGFUSEHOST or LANGFUSEBASEURL.
Step 4: Initialize and Verify (v4+ Modular SDK)

// src/lib/langfuse.ts
import { LangfuseClient } from "@langfuse/client";
import { startActiveObservation } from "@langfuse/tracing";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

// 1. Register the OpenTelemetry span processor (once at app startup)
const sdk = new NodeSDK({
  spanProcessors: [new Langfuse

                

              

                
                  
                  
                  langfuse-local-dev-loop
                  SKILL.md
                  View full skill →
                
                
                  Set up Langfuse local development workflow with hot reload and debugging.
                  
                      ReadWriteEditBash(npm:*)Bash(docker:*)Bash(pnpm:*)
                    
                
                
                  Langfuse Local Dev Loop
Overview
Fast local development workflow with Langfuse tracing, immediate trace visibility, debug logging, and optional self-hosted local instance via Docker.
Prerequisites

Completed langfuse-install-auth setup
Node.js 18+ with tsx for hot reload (npm install -D tsx)
Docker (optional, for self-hosted local instance)

Instructions
Step 1: Development Environment File

# .env.local (git-ignored)
LANGFUSE_PUBLIC_KEY=pk-lf-dev-...
LANGFUSE_SECRET_KEY=sk-lf-dev-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

# Dev-specific settings
NODE_ENV=development
OPENAI_API_KEY=sk-...

Step 2: Dev-Optimized Langfuse Setup (v4+)

// src/lib/langfuse-dev.ts
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseClient } from "@langfuse/client";

const isDev = process.env.NODE_ENV !== "production";

// Configure span processor with dev-friendly settings
const processor = new LangfuseSpanProcessor({
  // In dev: flush immediately for instant visibility
  ...(isDev && { exportIntervalMillis: 1000, maxExportBatchSize: 1 }),
});

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

export const langfuse = new LangfuseClient();

// Print trace URLs in development
export function logTrace(traceId: string) {
  if (isDev) {
    const host = process.env.LANGFUSE_BASE_URL || "https://cloud.langfuse.com";
    console.log(`\n  Trace: ${host}/trace/${traceId}\n`);
  }
}

// Clean shutdown
process.on("SIGINT", async () => {
  await sdk.shutdown();
  process.exit(0);
});

Step 3: Dev-Optimized Setup (v3 Legacy)

// src/lib/langfuse-dev.ts
import { Langfuse } from "langfuse";

const isDev = process.env.NODE_ENV !== "production";

export const langfuse = new Langfuse({
  flushAt: isDev ? 1 : 15,          // Immediate flush in dev
  flushInterval: isDev ? 1000 : 10000,
  ...(isDev && { debug: true }),     // Verbose SDK logging
});

export function logTraceUrl(trace: ReturnType<typeof langfuse.trace>) {
  if (isDev) {
    console.log(`\n  Trace: ${trace.getTraceUrl()}\n`);
  }
}

process.on("beforeExit", async () => {
  await langfuse.shutdownAsync();
});

Step 4: Hot Reload Scripts

{
  "scripts": {
    "dev": "tsx watch --env-file=.env.local src/index.ts",
    "dev:debug": "DEBUG=langfuse* tsx watch --env-file=.env.local src/index.ts",
    "dev:trace": "LANGFUSE_DEBUG=true tsx watch --env-file=.env.local src/index.ts"
  }
}

Step 5: Development Tracing Uti
                
              

                
                  
                  
                  langfuse-migration-deep-dive
                  SKILL.md
                  View full skill →
                
                
                  Execute complex Langfuse migrations including data migration and platform changes.
                  
                      ReadWriteEditBash(npm:*)
                    
                
                
                  Langfuse Migration Deep Dive
Current State
!npm list langfuse @langfuse/client 2>/dev/null | head -5 || echo 'No langfuse packages'
Overview
Comprehensive guide for complex migrations: cloud-to-self-hosted, LangSmith-to-Langfuse, cross-instance data migration, and zero-downtime dual-write patterns.
Prerequisites

Understanding of source and target Langfuse instances
API keys for both source and target
Git branch for migration work
Rollback plan documented

Migration Scenarios

Scenario
Complexity
Downtime
Data Loss Risk


Cloud to Cloud (different project)
Low
None
None


Cloud to Self-hosted
Medium
Minutes
Low


Self-hosted to Cloud
Medium
Minutes
Low


LangSmith to Langfuse
High
Hours
Medium


SDK v3 to v4+ (no data migration)
Low
None
None


Instructions
Step 1: Export Data from Source Instance

// scripts/export-langfuse.ts
import { LangfuseClient } from "@langfuse/client";
import { writeFileSync, mkdirSync } from "fs";

const source = new LangfuseClient({
  publicKey: process.env.SOURCE_LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.SOURCE_LANGFUSE_SECRET_KEY,
  baseUrl: process.env.SOURCE_LANGFUSE_BASE_URL,
});

async function exportAll(outputDir: string) {
  mkdirSync(outputDir, { recursive: true });

  // Export traces
  let page = 1;
  let allTraces: any[] = [];
  let hasMore = true;

  console.log("Exporting traces...");
  while (hasMore) {
    const result = await source.api.traces.list({ limit: 100, page });
    allTraces.push(...result.data);
    hasMore = result.data.length === 100;
    page++;
    await new Promise((r) => setTimeout(r, 200)); // Rate limit
  }
  writeFileSync(`${outputDir}/traces.json`, JSON.stringify(allTraces, null, 2));
  console.log(`  Exported ${allTraces.length} traces`);

  // Export scores
  page = 1;
  let allScores: any[] = [];
  hasMore = true;

  console.log("Exporting scores...");
  while (hasMore) {
    const result = await source.api.scores.list({ limit: 100, page });
    allScores.push(...result.data);
    hasMore = result.data.length === 100;
    page++;
    await new Promise((r) => setTimeout(r, 200));
  }
  writeFileSync(`${outputDir}/scores.json`, JSON.stringify(allScores, null, 2));
  console.log(`  Exported ${allScores.length} scores`);

  // Export prompts
  console.log("Exporting prompts...");
  const prompts = await source.api.prompts.list({ limit: 100 });
  writeFileSync(`${outputDir}/prompts.json`, JSON.stringify(prompts.data, null, 2));
  console.log(`  Expor

                

              

                
                  
                  
                  langfuse-multi-env-setup
                  SKILL.md
                  View full skill →
                
                
                  Configure Langfuse across development, staging, and production environments.
                  
                      ReadWriteEditBash(aws:*)Bash(gcloud:*)Bash(vault:*)
                    
                
                
                  Langfuse Multi-Environment Setup
Overview
Configure Langfuse across dev/staging/production with isolated API keys, environment-specific SDK settings, secret management, and CI/CD integration to prevent cross-environment data leakage.
Prerequisites

Separate Langfuse API key pairs per environment (or separate projects)
Secret management solution (env vars, Vault, AWS/GCP secrets)
CI/CD pipeline with environment-aware deployment

Environment Strategy

Environment
API Key Source
Langfuse Project
Settings


Development
.env.local
Dev project
Debug on, flush immediately, 100% sampling


Staging
CI/CD secrets
Staging project
Prod-like settings, 50% sampling


Production
Secret manager
Prod project
Optimized batching, 10% sampling


Instructions
Step 1: Environment-Specific Configuration

// src/config/langfuse.ts
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { LangfuseClient } from "@langfuse/client";

type Env = "development" | "staging" | "production";

interface LangfuseEnvConfig {
  exportIntervalMillis: number;
  maxExportBatchSize: number;
  debug: boolean;
  sampleRate: number;
}

const ENV_CONFIGS: Record<Env, LangfuseEnvConfig> = {
  development: {
    exportIntervalMillis: 1000,
    maxExportBatchSize: 1,
    debug: true,
    sampleRate: 1.0,
  },
  staging: {
    exportIntervalMillis: 5000,
    maxExportBatchSize: 25,
    debug: false,
    sampleRate: 0.5,
  },
  production: {
    exportIntervalMillis: 10000,
    maxExportBatchSize: 50,
    debug: false,
    sampleRate: 0.1,
  },
};

function detectEnvironment(): Env {
  const env = process.env.NODE_ENV || "development";
  if (env === "production") return "production";
  if (env === "staging" || process.env.VERCEL_ENV === "preview") return "staging";
  return "development";
}

export function initLangfuse() {
  const env = detectEnvironment();
  const config = ENV_CONFIGS[env];

  // Validate credentials
  const required = ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY"];
  for (const key of required) {
    if (!process.env[key]) {
      throw new Error(`${key} not set for environment: ${env}`);
    }
  }

  // Initialize OTel with env-specific settings
  const processor = new LangfuseSpanProcessor({
    exportIntervalMillis: config.exportIntervalMillis,
    maxExportBatchSize: config.maxExportBatchSize,
  });

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

  // Client for prompts, d

                

              

                
                  
                  
                  langfuse-observability
                  SKILL.md
                  View full skill →
                
                
                  Set up comprehensive observability for Langfuse with metrics, dashboards, and alerts.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Observability
Overview
Set up monitoring for your Langfuse integration: Prometheus metrics for trace/generation throughput, Grafana dashboards, alert rules, and integration with Langfuse's built-in analytics dashboards and Metrics API.
Prerequisites

Langfuse SDK integrated and producing traces
For custom metrics: Prometheus + Grafana (or compatible stack)
For Langfuse analytics: access to the Langfuse UI dashboard

Instructions
Step 1: Langfuse Built-In Dashboards
Langfuse provides pre-built dashboards in the UI at https://cloud.langfuse.com (or your self-hosted URL):

Overview: Total traces, generations, scores, and errors
Cost Dashboard: Token usage and costs over time, broken down by model, user, session
Latency Dashboard: Response times across models and user segments
Custom Dashboards: Build your own with the query engine (multi-level aggregations, filters by user/model/tag)

Accessing via Metrics API:

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

const langfuse = new LangfuseClient();

// Fetch aggregated metrics programmatically
const traces = await langfuse.api.traces.list({
  fromTimestamp: new Date(Date.now() - 3600000).toISOString(), // Last hour
  limit: 100,
});

console.log(`Traces in last hour: ${traces.data.length}`);

// Get observations with cost data
const observations = await langfuse.api.observations.list({
  type: "GENERATION",
  fromTimestamp: new Date(Date.now() - 86400000).toISOString(),
  limit: 500,
});

const totalCost = observations.data.reduce(
  (sum, obs) => sum + (obs.calculatedTotalCost || 0), 0
);
console.log(`Total cost (24h): $${totalCost.toFixed(4)}`);

Step 2: Prometheus Metrics for Your App
Track the health of your Langfuse integration with custom Prometheus metrics:

// src/lib/langfuse-metrics.ts
import { Counter, Histogram, Gauge, Registry } from "prom-client";

const registry = new Registry();

export const metrics = {
  tracesCreated: new Counter({
    name: "langfuse_traces_created_total",
    help: "Total traces created",
    labelNames: ["status"],
    registers: [registry],
  }),

  generationDuration: new Histogram({
    name: "langfuse_generation_duration_seconds",
    help: "LLM generation latency",
    labelNames: ["model"],
    buckets: [0.1, 0.5, 1, 2, 5, 10, 30],
    registers: [registry],
  }),

  tokensUsed: new Counter({
    name: "langfuse_tokens_total",
    help: "Total tokens used",
    labelNames: ["model", "type"],
    registers: [registry],
  }),

  costUsd: new Counter({
    name: "langfuse_cos

                

              

                
                  
                  
                  langfuse-performance-tuning
                  SKILL.md
                  View full skill →
                
                
                  Optimize Langfuse tracing performance for high-throughput applications.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Performance Tuning
Overview
Optimize Langfuse tracing for minimal overhead and maximum throughput: benchmark measurement, batch tuning, non-blocking patterns, payload optimization, sampling, and memory management.
Prerequisites

Existing Langfuse integration
Performance baseline to compare against
Understanding of async patterns

Performance Targets

Metric
Target
Critical


Trace creation overhead
< 1ms
< 5ms


Flush latency (batch)
< 100ms
< 500ms


Memory per active trace
< 1KB
< 5KB


CPU overhead
< 1%
< 5%


Instructions
Step 1: Benchmark Current Performance

// scripts/benchmark-langfuse.ts
import { performance } from "perf_hooks";
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

async function benchmark() {
  const sdk = new NodeSDK({
    spanProcessors: [new LangfuseSpanProcessor()],
  });
  sdk.start();

  const iterations = 1000;

  // Measure trace creation
  const timings: number[] = [];
  for (let i = 0; i < iterations; i++) {
    const start = performance.now();
    await startActiveObservation(`bench-${i}`, async () => {
      updateActiveObservation({ input: { i }, output: { done: true } });
    });
    timings.push(performance.now() - start);
  }

  const sorted = timings.sort((a, b) => a - b);
  console.log("=== Langfuse Performance Benchmark ===");
  console.log(`Iterations: ${iterations}`);
  console.log(`Mean:  ${(sorted.reduce((a, b) => a + b) / sorted.length).toFixed(3)}ms`);
  console.log(`P50:   ${sorted[Math.floor(sorted.length * 0.5)].toFixed(3)}ms`);
  console.log(`P95:   ${sorted[Math.floor(sorted.length * 0.95)].toFixed(3)}ms`);
  console.log(`P99:   ${sorted[Math.floor(sorted.length * 0.99)].toFixed(3)}ms`);

  const flushStart = performance.now();
  await sdk.shutdown();
  console.log(`Flush: ${(performance.now() - flushStart).toFixed(1)}ms`);
}

benchmark();

Step 2: Optimize Batch Configuration

// v4+: Tune OTel span processor
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

const processor = new LangfuseSpanProcessor({
  exportIntervalMillis: 10000,  // Flush every 10s (default: 5000)
  maxExportBatchSize: 100,      // Larger batches = fewer API calls
  maxQueueSize: 4096,           // Buffer more events before dropping
});

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

                
              

                
                  
                  
                  langfuse-prod-checklist
                  SKILL.md
                  View full skill →
                
                
                  Langfuse production readiness checklist and verification.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Langfuse Production Checklist
Overview
Comprehensive checklist for deploying Langfuse observability to production with verified configuration, error handling, graceful shutdown, monitoring, and a pre-deployment verification script.
Prerequisites

Development and staging testing completed
Production Langfuse project created with separate API keys
Secret management solution in place

Production Configuration
Recommended SDK Settings

// v4+ Production Config
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

const processor = new LangfuseSpanProcessor({
  exportIntervalMillis: 5000,  // Flush every 5s
  maxExportBatchSize: 50,      // Batch size
  maxQueueSize: 2048,          // Buffer limit
});

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

// Graceful shutdown on all signals
for (const signal of ["SIGTERM", "SIGINT", "SIGUSR2"]) {
  process.on(signal, async () => {
    await sdk.shutdown();
    process.exit(0);
  });
}


// v3 Legacy Production Config
import { Langfuse } from "langfuse";

const langfuse = new Langfuse({
  flushAt: 25,            // Balance between latency and efficiency
  flushInterval: 5000,    // 5 second flush interval
  requestTimeout: 15000,  // 15s timeout
  enabled: true,          // Explicitly enable
});

process.on("beforeExit", () => langfuse.shutdownAsync());
process.on("SIGTERM", () => langfuse.shutdownAsync().then(() => process.exit(0)));

Production Error Handling

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

// Wrap all traced operations with error safety
const tracedEndpoint = observe({ name: "api-endpoint" }, async (req: Request) => {
  try {
    updateActiveObservation({
      input: { path: req.url, method: req.method },
      metadata: { userId: req.userId },
    });

    const result = await processRequest(req);

    updateActiveObservation({ output: { status: 200 } });
    return result;
  } catch (error) {
    // Log error to trace -- don't let tracing error mask app error
    try {
      updateActiveObservation({
        output: { error: String(error) },
        metadata: { level: "ERROR" },
      });
    } catch {
      // Tracing failure must never break the app
    }
    throw error;
  }
});

Pre-Deployment Verification Script

// scripts/verify-langfuse-prod.ts
import { LangfuseClient } from "@langfuse/client";
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";

async function verify() {
  const checks: Array<{ na

                

              

                
                  
                  
                  langfuse-rate-limits
                  SKILL.md
                  View full skill →
                
                
                  Implement Langfuse rate limiting, batching, and backoff patterns.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Rate Limits
Overview
Handle Langfuse API rate limits with optimized SDK batching, exponential backoff with jitter, concurrent request limiting, and configurable sampling for ultra-high-volume workloads.
Prerequisites

Langfuse SDK installed and configured
High-volume trace workload (1,000+ events/minute)

Instructions
Step 1: Optimize SDK Batching Configuration
The Langfuse SDK batches events internally before sending. Tuning batch settings is the first defense against rate limits.

// v3 Legacy: Direct configuration
import { Langfuse } from "langfuse";

const langfuse = new Langfuse({
  flushAt: 50,           // Events per batch (default: 15, max ~200)
  flushInterval: 10000,  // Milliseconds between flushes (default: 10000)
  requestTimeout: 30000, // Timeout per batch request
});

// v4+: Configure via OTel span processor
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

const processor = new LangfuseSpanProcessor({
  exportIntervalMillis: 10000, // Flush interval
  maxExportBatchSize: 50,      // Events per batch
});

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

Step 2: Implement Retry with Exponential Backoff
For custom API calls (scores, datasets, prompts) that hit rate limits:

async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries?: number; baseDelayMs?: number; maxDelayMs?: number } = {}
): Promise<T> {
  const { maxRetries = 5, baseDelayMs = 1000, maxDelayMs = 30000 } = options;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      const status = error?.status || error?.response?.status;

      // Only retry on rate limits (429) and server errors (5xx)
      if (attempt === maxRetries || (status && status < 429)) {
        throw error;
      }

      // Honor Retry-After header if present
      const retryAfter = error?.response?.headers?.["retry-after"];
      let delay: number;

      if (retryAfter) {
        delay = parseInt(retryAfter, 10) * 1000;
      } else {
        // Exponential backoff with jitter
        delay = Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
        delay += Math.random() * 500; // Jitter
      }

      console.warn(`Rate limited. Retry ${attempt + 1}/${maxRetries} in ${Math.round(delay)}ms`);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

// Usage with Langfuse client operations
const langfuse = new LangfuseClient();

await withRetry(() =>
  langfuse.score.create({
    traceId: "trace-123",
    name: "quality",
    value: 0.95,
    dataType: "NUMERIC",
  })

                

              

                
                  
                  
                  langfuse-reference-architecture
                  SKILL.md
                  View full skill →
                
                
                  Production-grade Langfuse architecture patterns and best practices.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Reference Architecture
Overview
Production-grade architecture patterns for Langfuse LLM observability: singleton SDK, context propagation with AsyncLocalStorage, cross-service trace correlation, multi-environment configurations, and scale strategies.
Prerequisites

Understanding of distributed systems and async patterns
Node.js 18+ with OpenTelemetry SDK
For v4+: @langfuse/tracing, @langfuse/otel, @opentelemetry/sdk-node

Architecture Tiers

Tier
Scale
Architecture
Langfuse Host


Starter
< 100K traces/day
Direct SDK, Cloud
Langfuse Cloud


Growth
100K-1M traces/day
Singleton + batching
Cloud or Self-hosted


Enterprise
1M+ traces/day
Queue-buffered + sampling
Self-hosted (HA)


Instructions
Pattern 1: Singleton SDK with Context Propagation

// src/lib/tracing.ts -- Single module for all tracing
import { LangfuseClient } from "@langfuse/client";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { AsyncLocalStorage } from "async_hooks";

// Singleton OTel SDK
let sdk: NodeSDK | null = null;

export function initTracing() {
  if (sdk) return sdk;

  sdk = new NodeSDK({
    spanProcessors: [
      new LangfuseSpanProcessor({
        exportIntervalMillis: 5000,
        maxExportBatchSize: 50,
      }),
    ],
  });
  sdk.start();

  // Graceful shutdown
  for (const signal of ["SIGTERM", "SIGINT"]) {
    process.on(signal, async () => {
      console.log(`Received ${signal}, flushing traces...`);
      await sdk?.shutdown();
      process.exit(0);
    });
  }

  return sdk;
}

// Singleton client for non-tracing operations
let client: LangfuseClient | null = null;

export function getLangfuseClient(): LangfuseClient {
  if (!client) client = new LangfuseClient();
  return client;
}

// Request context for user/session tracking
interface RequestContext {
  userId?: string;
  sessionId?: string;
  requestId: string;
}

const requestStore = new AsyncLocalStorage<RequestContext>();

export function getRequestContext(): RequestContext | undefined {
  return requestStore.getStore();
}

export function runWithContext<T>(ctx: RequestContext, fn: () => T): T {
  return requestStore.run(ctx, fn);
}

Pattern 2: Express Middleware for Automatic Tracing

// src/middleware/tracing.ts
import { startActiveObservation, updateActiveObservation } from "@langfuse/tracing";
import { runWithContext, getRequestContext } from "../lib/tracing";
import 

                

              

                
                  
                  
                  langfuse-sdk-patterns
                  SKILL.md
                  View full skill →
                
                
                  Langfuse SDK best practices, patterns, and idiomatic usage.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse SDK Patterns
Overview
Production-quality patterns for the Langfuse SDK: singleton clients, the observe wrapper, startActiveObservation for nested traces, session tracking, graceful shutdown, and error-safe tracing.
Prerequisites

Completed langfuse-install-auth setup
Understanding of async/await patterns
For v4+: @langfuse/tracing, @langfuse/otel, @opentelemetry/sdk-node

Instructions
Pattern 1: Singleton Client with Graceful Shutdown

// src/lib/langfuse.ts -- single file, import everywhere
import { LangfuseClient } from "@langfuse/client";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

// Singleton client for prompts, datasets, scores
let client: LangfuseClient | null = null;
export function getLangfuseClient(): LangfuseClient {
  if (!client) {
    client = new LangfuseClient();
  }
  return client;
}

// One-time OTel setup (call at app entry point)
let sdk: NodeSDK | null = null;
export function initTracing(): NodeSDK {
  if (!sdk) {
    sdk = new NodeSDK({
      spanProcessors: [new LangfuseSpanProcessor()],
    });
    sdk.start();

    // Graceful shutdown on process exit
    const shutdown = async () => {
      await sdk?.shutdown();
      process.exit(0);
    };
    process.on("SIGTERM", shutdown);
    process.on("SIGINT", shutdown);
  }
  return sdk;
}

Legacy v3 singleton:

import { Langfuse } from "langfuse";

let instance: Langfuse | null = null;

export function getLangfuse(): Langfuse {
  if (!instance) {
    instance = new Langfuse({
      flushAt: 15,
      flushInterval: 10000,
    });
    process.on("beforeExit", () => instance?.shutdownAsync());
  }
  return instance;
}

Pattern 2: observe Wrapper for Existing Functions
The observe wrapper is the most ergonomic way to add tracing. It wraps any function and auto-creates a span.

import { observe, updateActiveObservation } from "@langfuse/tracing";

// Wrap existing functions -- no internal changes needed
const fetchUserProfile = observe(async (userId: string) => {
  updateActiveObservation({ input: { userId } });
  const profile = await db.users.findById(userId);
  updateActiveObservation({ output: { found: !!profile } });
  return profile;
});

// Mark LLM calls as generations
const summarize = observe(
  { name: "summarize-text", asType: "generation" },
  async (text: string) => {
    updateActiveObservation({ model: "gpt-4o-mini", input: text });
    const result = await openai.chat.completions.create({
      model: "gpt-4o-min

                

              

                
                  
                  
                  langfuse-security-basics
                  SKILL.md
                  View full skill →
                
                
                  Implement Langfuse security best practices for API keys and data privacy.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Security Basics
Overview
Security practices for Langfuse LLM observability: credential management, PII scrubbing before tracing, self-hosted hardening, data retention, and secret scanning.
Prerequisites

Langfuse instance (cloud or self-hosted)
API keys provisioned
Understanding of data privacy requirements (GDPR, SOC2, HIPAA)

Instructions
Step 1: Credential Security
Langfuse uses two keys with different security profiles:

// Startup validation -- catch misconfigurations early
function validateLangfuseCredentials() {
  const publicKey = process.env.LANGFUSE_PUBLIC_KEY;
  const secretKey = process.env.LANGFUSE_SECRET_KEY;

  if (!publicKey || !secretKey) {
    throw new Error("LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY are required");
  }

  // Catch key swap (common mistake)
  if (secretKey.startsWith("pk-lf-")) {
    throw new Error("LANGFUSE_SECRET_KEY contains a public key (pk-lf-). Keys are swapped.");
  }

  if (publicKey.startsWith("sk-lf-")) {
    throw new Error("LANGFUSE_PUBLIC_KEY contains a secret key (sk-lf-). Keys are swapped.");
  }

  return { publicKey, secretKey };
}

// Use validated credentials
const { publicKey, secretKey } = validateLangfuseCredentials();

Key security rules:

Public key (pk-lf-...): Identifies the project. Safe in client-side code.
Secret key (sk-lf-...): Grants write access. Server-side only.
Store in environment variables or secret manager -- never in source code.
Rotate keys immediately if exposed in logs, git, or error reports.

Step 2: PII Scrubbing Before Tracing
Langfuse stores everything you send. Scrub PII from inputs and outputs before tracing.

// src/lib/pii-scrubber.ts

const PII_PATTERNS: Array<{ regex: RegExp; replacement: string }> = [
  { regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z]{2,}\b/gi, replacement: "[EMAIL]" },
  { regex: /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g, replacement: "[PHONE]" },
  { regex: /\b\d{3}-\d{2}-\d{4}\b/g, replacement: "[SSN]" },
  { regex: /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/g, replacement: "[CARD]" },
  { regex: /\b(?:sk|pk)-[a-zA-Z0-9_-]{20,}\b/g, replacement: "[API_KEY]" },
];

export function scrubPII(text: string): string {
  let scrubbed = text;
  for (const { regex, replacement } of PII_PATTERNS) {
    scrubbed = scrubbed.replace(regex, replacement);
  }
  return scrubbed;
}

export function scrubObject(obj: any): any {
  if (typeof obj === "string") return scrubPII(obj);
  if (Array.isArray(obj)) return obj.map(scrubObject);
  if (typeof obj === "object" && obj !== null) {
    const result: Record<string, an

                

              

                
                  
                  
                  langfuse-upgrade-migration
                  SKILL.md
                  View full skill →
                
                
                  Upgrade Langfuse SDK versions and migrate between API changes.
                  
                      ReadWriteEditBash(npm:*)Bash(pip:*)
                    
                
                
                  Langfuse Upgrade & Migration
Current State
!npm list langfuse @langfuse/client @langfuse/tracing @langfuse/otel 2>/dev/null | head -10 || echo 'No langfuse packages found'
!pip show langfuse 2>/dev/null | grep -E "Name|Version" || echo 'Python langfuse not installed'
Overview
Step-by-step guide for upgrading the Langfuse SDK across major versions. Covers v3 to v4 (OTel rewrite), v4 to v5, breaking changes, and automated codemods.
Prerequisites

Existing Langfuse integration
Test suite covering traced operations
Git branch for the upgrade

Version Roadmap

SDK
Package
Architecture
Status


v3
langfuse (single)
Custom, Langfuse class
Legacy


v4
@langfuse/client, @langfuse/tracing, @langfuse/otel
OpenTelemetry-based
Stable


v5
@langfuse/client, @langfuse/tracing, @langfuse/otel
OpenTelemetry + improvements
Latest


Instructions
Step 1: Check Current Version and Plan

set -euo pipefail
# Check what you have
npm list langfuse @langfuse/client @langfuse/tracing 2>/dev/null

# Check latest available
npm info @langfuse/client version
npm info @langfuse/tracing version
npm info langfuse version

# Python
pip show langfuse 2>/dev/null | grep Version
pip index versions langfuse 2>/dev/null | head -3

Step 2: v3 to v4 Migration (TypeScript)
This is the biggest migration -- v4 rewrites tracing on OpenTelemetry.
2a. Install new packages:

set -euo pipefail
# Install v4+ packages
npm install @langfuse/client @langfuse/tracing @langfuse/otel @opentelemetry/sdk-node

# Keep langfuse v3 temporarily for comparison
# Remove after migration: npm uninstall langfuse

2b. Update initialization:

// BEFORE (v3):
import { Langfuse } from "langfuse";
const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  baseUrl: process.env.LANGFUSE_HOST,
});

// AFTER (v4+):
import { LangfuseClient } from "@langfuse/client";
import { LangfuseSpanProcessor } from "@langfuse/otel";
import { NodeSDK } from "@opentelemetry/sdk-node";

// OTel setup (once at entry point)
const sdk = new NodeSDK({
  spanProcessors: [new LangfuseSpanProcessor()],
});
sdk.start();

// Client for prompts, datasets, scores
const langfuse = new LangfuseClient();

2c. Update tracing calls:

                
              

                
                  
                  
                  langfuse-webhooks-events
                  SKILL.md
                  View full skill →
                
                
                  Configure Langfuse webhooks for prompt change notifications and event-driven workflows.
                  
                      ReadWriteEdit
                    
                
                
                  Langfuse Webhooks & Events
Overview
Configure Langfuse webhooks to receive notifications on prompt version changes. Langfuse supports webhook events for prompt lifecycle: Created, Updated (labels/tags changed), and Deleted. Use webhooks to trigger CI/CD pipelines, sync prompts to external systems, or notify teams via Slack.
Prerequisites

Langfuse Cloud or self-hosted instance
HTTPS endpoint to receive webhook POST requests
Webhook secret for HMAC signature verification

Instructions
Step 1: Create Webhook Endpoint

// app/api/webhooks/langfuse/route.ts (Next.js App Router)
import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";

const WEBHOOK_SECRET = process.env.LANGFUSE_WEBHOOK_SECRET!;

interface LangfuseWebhookEvent {
  event: "prompt.created" | "prompt.updated" | "prompt.deleted";
  timestamp: string;
  data: {
    promptName: string;
    promptVersion: number;
    labels?: string[];
    projectId: string;
    [key: string]: any;
  };
}

// Verify HMAC SHA-256 signature
function verifySignature(payload: string, signature: string): boolean {
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

export async function POST(request: NextRequest) {
  const payload = await request.text();
  const signature = request.headers.get("x-langfuse-signature");

  // Verify webhook authenticity
  if (!signature || !verifySignature(payload, signature)) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }

  const event: LangfuseWebhookEvent = JSON.parse(payload);
  console.log(`Langfuse webhook: ${event.event} - ${event.data.promptName}`);

  switch (event.event) {
    case "prompt.created":
      await handlePromptCreated(event.data);
      break;
    case "prompt.updated":
      await handlePromptUpdated(event.data);
      break;
    case "prompt.deleted":
      await handlePromptDeleted(event.data);
      break;
  }

  return NextResponse.json({ received: true });
}

async function handlePromptCreated(data: LangfuseWebhookEvent["data"]) {
  // Trigger CI/CD pipeline for new prompt version
  if (data.labels?.includes("production")) {
    await triggerPromptDeployPipeline(data.promptName, data.promptVersion);
  }

  await notifySlack({
    text: `New prompt version: *${data.promptName}* v${data.promptVersion}`,
    labels: data.labels,
  });
}

async function handlePromptUpdated(data: LangfuseWebhookEvent["data"]) {
  // Label change -- check if promoted to production
  if (data.labels?.includes("production")) {
    awa

                

              

          

        

      
      

      
      

      
      

      
      
  Ready to use langfuse-pack?
  
    
    
  




      
      
          Related Plugins
          
            
                ai-ethics-validator
                AI ethics and fairness validation
              
                ai-experiment-logger
                Track and analyze AI experiments with a web dashboard and MCP tools
              
                ai-ml-engineering-pack
                Professional AI/ML Engineering toolkit: Prompt engineering, LLM integration, RAG systems, AI safety with 12 expert plugins
              
                ai-sdk-agents
                Multi-agent orchestration with AI SDK v5 - handoffs, routing, and coordination for any AI provider (OpenAI, Anthropic, Google)
              
                anomaly-detection-system
                Detect anomalies and outliers in data
              
                automl-pipeline-builder
                Build AutoML pipelines
              
          
        

      
      
          Tags
          
            langfuseobservabilitytracingpromptsevaluationllm-opsmonitoring
          
        
    
  

  

    

    
    
        
            
                Stay in the Loop
                
                    
                    
                    
                
                No spam. Unsubscribe anytime.
            

            
                
                    Product
                    
                        Explore
                        Skills
                        Cowork
                        Compare
                        Tools
                    
                
                
                    Resources
                    
                        Docs
                        Changelog
                        Collections
                        Playbooks
                        Research
                        Learning
                    
                
                
                    Company
                    
                        Community
                        Spotlight
                        GitHub
                    
                
                
                    Legal
                    
                        Privacy
                        Terms
                        Acceptable Use
                    
                
            

            
                Tons of Skills by Intent Solutions. Marine. Citadel Grad. 20 years ops → self-taught dev → AI architect.
                © 2026 Tons of Skills | Intent Solutions

Role	View Traces	Create Traces	Manage Prompts	Manage Members	Manage Billing
Owner	Yes	Yes	Yes	Yes	Yes
Admin	Yes	Yes	Yes	Yes	No
Member	Yes	Yes	Yes	No	No
Viewer	Yes	No	No	No	No

Severity	Description	Response Time	Example
P1	Application impacted by tracing	15 min	SDK throwing unhandled errors, blocking requests
P2	Traces not appearing, no app impact	1 hour	Missing observability data
P3	Degraded performance from tracing	4 hours	High latency from flush backlog
P4	Minor issues	24 hours	Occasional missing traces