LangfuseExporter

Sends Tracing data to Langfuse for observability.

Constructor

new LangfuseExporter(config: LangfuseExporterConfig)

LangfuseExporterConfig

interface LangfuseExporterConfig extends BaseExporterConfig {
  publicKey?: string;
  secretKey?: string;
  baseUrl?: string;
  realtime?: boolean;
  options?: any;
}

Extends BaseExporterConfig, which includes:

• logger?: IMastraLogger - Logger instance
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Log level (default: INFO)

Methods

exportTracingEvent

async exportTracingEvent(event: TracingEvent): Promise<void>

Exports a tracing event to Langfuse.

export

async export(spans: ReadOnlySpan[]): Promise<void>

Batch exports spans to Langfuse.

shutdown

async shutdown(): Promise<void>

Flushes pending data and shuts down the client.

Usage

import { LangfuseExporter } from "@mastra/langfuse";

const exporter = new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  baseUrl: "https://cloud.langfuse.com",
  realtime: true,
});

Span Mapping

• Root spans → Langfuse traces
• MODEL_GENERATION spans → Langfuse generations
• All other spans → Langfuse spans
• Event spans → Langfuse events

Prompt Linking

Link LLM generations to Langfuse Prompt Management using the withLangfusePrompt helper:

import { buildTracingOptions } from "@mastra/observability";
import { withLangfusePrompt } from "@mastra/langfuse";
import { Langfuse } from "langfuse";

const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
});

const prompt = await langfuse.getPrompt("customer-support");

const agent = new Agent({
  name: "support-agent",
  instructions: prompt.prompt,
  model: openai("gpt-4o"),
  defaultGenerateOptions: {
    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
  },
});

Helper Functions

withLangfusePrompt(prompt)

Adds Langfuse prompt metadata to tracing options.

// With Langfuse SDK prompt object
withLangfusePrompt(prompt)

// With manual fields
withLangfusePrompt({ name: "my-prompt", version: 1 })
withLangfusePrompt({ id: "prompt-uuid" })

When metadata.langfuse.prompt is set on a MODEL_GENERATION span (with either id alone, or name + version), the exporter automatically links the generation to the prompt in Langfuse.