Langfuse exporter

Langfuse 是一个专为 LLM 应用设计的开源可观测性平台。Langfuse exporter 会将 Trace 发送到 Langfuse，帮助你深入了解模型性能、token 用量和对话流程。

安装

npm

npm install @mastra/langfuse@latest

pnpm

pnpm add @mastra/langfuse@latest

Yarn

yarn add @mastra/langfuse@latest

Bun

bun add @mastra/langfuse@latest

配置

前提条件

1. Langfuse 账户：在 cloud.langfuse.com 注册，或进行自托管部署
2. API key：在 Langfuse Settings → API Keys 中创建公钥/私钥对
3. 环境变量：设置凭据

.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

零配置设置

设置环境变量后，无需任何配置即可使用 exporter：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      langfuse: {
        serviceName: 'my-service',
        exporters: [new LangfuseExporter()],
      },
    },
  }),
})

显式配置

你也可以直接传入凭据（优先于环境变量）：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

export const mastra = new Mastra({
  observability: new 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,
            environment: process.env.NODE_ENV,
            release: process.env.GIT_COMMIT,
          }),
        ],
      },
    },
  }),
})

配置选项

实时模式与批处理模式

Langfuse exporter 支持两种 Trace 发送模式：

实时模式（开发）

Trace 会立即显示在 Langfuse 仪表板中，非常适合调试：

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

批处理模式（生产）

通过自动批处理获得更好的性能：

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

为高流量 Trace 调整批处理

对于自托管 Langfuse 部署，或每秒生成许多 span 的流式运行，可以调整 OTEL 批次大小和刷新间隔，以减轻 Langfuse ingestion endpoint 的请求压力：

new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  flushAt: 500, // Maximum spans per OTEL export batch
  flushInterval: 20, // Maximum seconds between flushes
})

要完全抑制高流量 span 类型（例如流式响应中的 MODEL_CHUNK span），请使用可观测性级别的 excludeSpanTypes 选项，而不是配置 exporter：

import { SpanType } from '@mastra/core/observability'

new Observability({
  configs: {
    langfuse: {
      serviceName: 'my-service',
      exporters: [new LangfuseExporter()],
      excludeSpanTypes: [SpanType.MODEL_CHUNK],
    },
  },
})

完整配置

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
  flushAt: 500, // Maximum spans per OTEL export batch
  flushInterval: 20, // Maximum seconds between flushes
  logLevel: 'info', // Diagnostic logging: debug | info | warn | error

  // Langfuse-specific settings
  environment: process.env.NODE_ENV, // Shows in Langfuse UI for filtering
  release: process.env.GIT_COMMIT, // Git commit hash for version tracking
})

按 Agent 限定 evaluator

Langfuse evaluator（如 LLM-as-a-Judge）可以配置为仅针对特定 Trace 运行。Mastra Langfuse exporter 会自动将每个 Trace 限定到启动它的 Agent 或 Workflow，使 Trace 级过滤器匹配正确的运行。

对于根 span 为 AGENT_RUN 的每条 Trace，exporter 会设置：

• langfuse.trace.name：Agent 名称（未设置名称时使用 id）
• langfuse.trace.metadata.agentId：Agent id
• langfuse.trace.metadata.agentName：Agent 名称

同样，根 span 为 WORKFLOW_RUN 时会设置 langfuse.trace.metadata.workflowId 和 langfuse.trace.metadata.workflowName。

要将 evaluator 限定到特定 Agent，请在 Langfuse 中配置以下任一过滤器：

• Trace name：等于 Agent 名称（例如 weather-agent）。
• Metadata：agentId 等于 Agent id。

Langfuse evaluator 过滤器中的 Trace name 下拉列表会列出所有已出现的不同值，因此每个 Agent 只要至少生成过一条 Trace，就会显示为单独选项。

如果通过 mastra.metadata.traceName 设置自定义 traceName，该值优先于默认 Agent 名称。

自定义 Trace 元数据

Langfuse 只能按顶层元数据过滤和分组 Trace，嵌套元数据键不能用于过滤或分组。

要添加自己的顶层元数据，请在 span 元数据的 langfuse 下设置键。Exporter 会将每个键转发到 langfuse.trace.metadata.<key>，使其可在 Langfuse 中过滤：

const tracingOptions = {
  metadata: {
    langfuse: {
      customerId: 'cust_123',
      tier: 'enterprise',
    },
  },
}

此示例会生成 langfuse.trace.metadata.customerId 和 langfuse.trace.metadata.tier。

注意：

• 保留的 prompt 键用于 prompt linking，不会作为 Trace 元数据转发。
• 保留的身份键 agentId、agentName、workflowId 和 workflowName 根据根 span 设置，并优先于同名自定义值。
• 由于 Langfuse 将 Trace 元数据属性映射为字符串，值会以字符串形式发送。数字、布尔值和对象使用 JSON 序列化。Langfuse Cloud 会在 ingestion 时将其还原为原始类型。

Prompt linking

你可以将 LLM 生成关联到 Langfuse Prompt Management 中存储的 prompt，从而为 prompt 提供版本跟踪和指标。

使用 helper（推荐）

将 withLangfusePrompt 与 buildTracingOptions 配合使用，可获得最简洁的 API：

src/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'
import { buildTracingOptions } from '@mastra/observability'
import { LangfuseExporter, withLangfusePrompt } from '@mastra/langfuse'

const exporter = new LangfuseExporter()

// Fetch the prompt from Langfuse Prompt Management via the client
const prompt = await exporter.client.prompt.get('customer-support', { type: 'text' })

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'support-agent',
  instructions: prompt.compile(), // Use the prompt text from Langfuse
  model: 'openai/gpt-5.6-sol',
  defaultGenerateOptions: {
    tracingOptions: buildTracingOptions(
      withLangfusePrompt({ name: prompt.name, version: prompt.version }),
    ),
  },
})

withLangfusePrompt helper 接受用于 prompt linking 的 name 和 version 字段。Langfuse v5 要求同时提供这两个字段。

手动字段

如果不使用 Langfuse SDK，也可以手动传入字段：

const tracingOptions = buildTracingOptions(withLangfusePrompt({ name: 'my-prompt', version: 1 }))

Prompt 对象字段

Prompt 对象同时需要 name 和 version：

字段	类型	说明
name	string	Langfuse 中的 prompt 名称
version	number	prompt 版本号

在 MODEL_GENERATION span 上设置后，Langfuse exporter 会自动将生成关联到对应 prompt。

相关内容

• Tracing 概览
• Langfuse 文档
• Langfuse Prompt Management