> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Langfuse exporter

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

## 安装

**npm**:

```bash
npm install @mastra/langfuse@latest
```

**pnpm**:

```bash
pnpm add @mastra/langfuse@latest
```

**Yarn**:

```bash
yarn add @mastra/langfuse@latest
```

**Bun**:

```bash
bun add @mastra/langfuse@latest
```

## 配置

### 前提条件

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

```bash
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：

```typescript
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()],
      },
    },
  }),
})
```

### 显式配置

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

```typescript
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 仪表板中，非常适合调试：

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

#### 批处理模式（生产）

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

```typescript
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 的请求压力：

```typescript
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` 选项](https://mastra.zisheng.pro/reference/observability/tracing/span-filtering)，而不是配置 exporter：

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

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

### 完整配置

```typescript
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 中过滤：

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

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

注意：

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

## Prompt linking

你可以将 LLM 生成关联到 [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management) 中存储的 prompt，从而为 prompt 提供版本跟踪和指标。

### 使用 helper（推荐）

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

```typescript
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，也可以手动传入字段：

```typescript
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 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [Langfuse 文档](https://langfuse.com/docs)
- [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management)