Langfuse Plugin for Genkit

September 8, 2025 · View on GitHub

The Langfuse plugin for Genkit provides observability and tracing for your Genkit applications by automatically exporting traces to Langfuse.

Installation

npm install genkit-langfuse

Configuration

Set up your Langfuse credentials as environment variables:

export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_BASE_URL="https://cloud.langfuse.com"  # optional, defaults to cloud

Usage

Plugin Approach (Recommended)

The plugin can be registered with Genkit's plugin system:

import { genkit } from 'genkit';
import { langfuse } from 'genkit-langfuse';

const ai = genkit({
  plugins: [
    langfuse({
      secretKey: process.env.LANGFUSE_SECRET_KEY!,
      publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
      baseUrl: process.env.LANGFUSE_BASE_URL, // optional
      debug: true, // optional
      forceDevExport: true, // enable in development
    })
  ],
});

Standalone Telemetry Setup

Alternatively, you can enable telemetry independently (useful for advanced configurations):

import { enableLangfuseTelemetry } from 'genkit-langfuse';
import { genkit } from 'genkit';

// Enable Langfuse telemetry before genkit initialization
await enableLangfuseTelemetry({
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  baseUrl: process.env.LANGFUSE_BASE_URL, // optional
  debug: true, // optional
  forceDevExport: true, // enable in development
});

const ai = genkit({
  plugins: [/* your other plugins */],
});

Advanced Configuration

await enableLangfuseTelemetry({
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  baseUrl: 'https://your-langfuse-instance.com',
  debug: true,
  
  // Development vs Production settings (following Genkit patterns)
  forceDevExport: true, // Force export in development
  flushAt: 1, // Immediate export in dev (20 in production)
  flushInterval: 1000, // 1s in dev (10s in production)
  exportTimeoutMillis: 10000, // HTTP timeout
  maxQueueSize: 1000, // Max queued spans
  
  // Custom cost calculation
  calculateCost: (modelName, usage) => {
    const rates = {
      'gemini-1.5-flash': { input: 0.075, output: 0.3 },
      'gemini-1.5-pro': { input: 3.5, output: 10.5 },
      'gpt-4': { input: 30, output: 60 },
    };
    const rate = rates[modelName] || { input: 0, output: 0 };
    return (usage.inputTokens * rate.input + usage.outputTokens * rate.output) / 1_000_000;
  },
  
  // Custom span filtering
  spanFilter: (span) => {
    // Only export model calls and flows
    return span.spanType === 'model' || span.spanType === 'flow';
  },
});

Features

Automatic Trace Export

The plugin automatically exports Genkit traces to Langfuse with the following mapping:

Generations: LLM/model calls are exported as Langfuse generations
Traces: Root spans and flows are exported as Langfuse traces
Spans: Intermediate operations are exported as Langfuse spans

Session Tracking

When using Genkit's chat functionality, session information is automatically included:

const chat = ai.chat({ sessionId: 'user-123' });
await chat.send('Hello!');
// Langfuse will receive sessionId: 'user-123'

Rich Metadata

The plugin captures comprehensive metadata including:

Model name and provider
Token usage (input/output/total)
Configuration parameters
Execution state and timing
Session and thread information
Custom metadata from spans

Cost Tracking

Automatic cost estimation for popular models, or provide custom cost calculation:

calculateCost: (modelName, usage) => {
  // Your custom cost calculation logic
  return estimatedCost;
}

What Gets Exported

Generations (LLM Calls)

Model name and provider (e.g., googleai/gemini-1.5-flash)
Input prompts and configuration
Output responses and token usage
Execution timing and performance metrics
Session and user context
Cost estimation (if configured)

Traces (Flows/Root Operations)

Flow name and input/output
Total execution time
Session context
Nested span hierarchy
Complete request lifecycle

Spans (Intermediate Operations)

Operation name and type (tools, utilities, etc.)
Input/output data
Execution timing
Parent-child relationships
Genkit-specific metadata

Development & Debugging

Development Mode

The plugin automatically detects development environment and uses faster export settings:

// Automatically enables immediate export in development
await enableLangfuseTelemetry({
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  forceDevExport: true, // Force development behavior
  debug: true, // Enable detailed logging
});

Debug Output

With debug: true, you'll see detailed logs including:

Span lifecycle (start/end)
Export batches and success status
HTTP communication status
Langfuse API responses
Performance metrics

Troubleshooting

If traces aren't appearing in Langfuse:

Check debug logs for HTTP errors
Verify credentials are correct
Ensure forceDevExport: true in development
Check network connectivity to Langfuse API

Configuration Options

Option	Type	Required	Default	Description
`secretKey`	string	✅	-	Langfuse secret key
`publicKey`	string	✅	-	Langfuse public key
`baseUrl`	string	❌	`https://cloud.langfuse.com`	Langfuse API base URL
`debug`	boolean	❌	`false`	Enable detailed logging
`forceDevExport`	boolean	❌	`false`	Force export in development
`flushAt`	number	❌	1 (dev) / 20 (prod)	Batch size for exports
`flushInterval`	number	❌	1000 (dev) / 10000 (prod)	Export interval in ms
`exportTimeoutMillis`	number	❌	30000	HTTP request timeout
`maxQueueSize`	number	❌	1000	Maximum queued spans
`calculateCost`	function	❌	-	Custom cost calculation
`spanFilter`	function	❌	-	Filter which spans to export

Environment Variables

LANGFUSE_SECRET_KEY: Your Langfuse secret key (required)
LANGFUSE_PUBLIC_KEY: Your Langfuse public key (required)
LANGFUSE_BASE_URL: Langfuse API base URL (optional, defaults to cloud)
NODE_ENV: Automatically detected for development settings

TypeScript Support

The plugin includes full TypeScript support with detailed type definitions for configuration options and metadata structures.

Follow

Firebase - Official Twitter account for Firebase.
Genkit Discord server - Official Discord server for Genkit.
Genkit GitHub - Official GitHub repository for Genkit.