Skip to main content

Langfuse Exporter

Langfuse is an open-source observability platform specifically designed for LLM applications. The Langfuse exporter sends your AI traces to Langfuse, providing detailed insights into model performance, token usage, and conversation flows.

When to Use LangfuseDirect link to When to Use Langfuse

Langfuse is ideal when you need:

  • LLM-specific analytics - Token usage, costs, latency breakdown
  • Conversation tracking - Session-based trace grouping
  • Quality scoring - Manual and automated evaluation scores
  • Model comparison - A/B testing and version comparisons
  • Self-hosted option - Deploy on your own infrastructure

InstallationDirect link to Installation

npm install @mastra/langfuse

ConfigurationDirect link to Configuration

PrerequisitesDirect link to Prerequisites

  1. Langfuse Account: Sign up at cloud.langfuse.com or deploy self-hosted
  2. API Keys: Create public/secret key pair in Langfuse Settings → API Keys
  3. Environment Variables: Set your credentials
.env
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxx
LANGFUSE_BASE_URL=https://cloud.langfuse.com  # Or your self-hosted URL

Basic SetupDirect link to Basic Setup

src/mastra/index.ts
import { Mastra } from "@mastra/core";
import { LangfuseExporter } from "@mastra/langfuse";

export const mastra = new Mastra({
  observability: {
    configs: {
      langfuse: {
        serviceName: "my-service",
        exporters: [
          new LangfuseExporter({
            publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
            secretKey: process.env.LANGFUSE_SECRET_KEY!,
            baseUrl: process.env.LANGFUSE_BASE_URL,
            options: {
              environment: process.env.NODE_ENV,
            },
          }),
        ],
      },
    },
  },
});

Configuration OptionsDirect link to Configuration Options

Realtime vs Batch ModeDirect link to Realtime vs Batch Mode

The Langfuse exporter supports two modes for sending traces:

Realtime Mode (Development)Direct link to Realtime Mode (Development)

Traces appear immediately in Langfuse dashboard, ideal for debugging:

new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  realtime: true, // Flush after each event
});

Batch Mode (Production)Direct link to Batch Mode (Production)

Better performance with automatic batching:

new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  realtime: false, // Default - batch traces
});

Complete ConfigurationDirect link to Complete Configuration

new LangfuseExporter({
  // Required credentials
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,

  // Optional settings
  baseUrl: process.env.LANGFUSE_BASE_URL, // Default: https://cloud.langfuse.com
  realtime: process.env.NODE_ENV === "development", // Dynamic mode selection
  logLevel: "info", // Diagnostic logging: debug | info | warn | error

  // Langfuse-specific options
  options: {
    environment: process.env.NODE_ENV, // Shows in UI for filtering
    version: process.env.APP_VERSION, // Track different versions
    release: process.env.GIT_COMMIT, // Git commit hash
  },
});