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 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

Installation​

npm install @mastra/langfuse

Configuration​

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 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 Options​

Realtime vs Batch Mode​

The Langfuse exporter supports two modes for sending traces:

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)​

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 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
  },
});