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

# Langfuse Exporter

[Langfuse](https://langfuse.com/) 是專為 LLM 應用程式而設的開源 Observability 平台。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 金鑰**：在 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 dashboard，適合用於除錯：

```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 批次大小及 flush 間距，以減輕 Langfuse 資料擷取端點的請求壓力：

```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），請使用 Observability 層級的 [`excludeSpanTypes` 選項](https://mastra.zisheng.pro/zh-TW/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 的範圍限定於啟動該 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 名稱

Root span 為 `WORKFLOW_RUN` 時也同樣適用，並會設定 `langfuse.trace.metadata.workflowId` 及 `langfuse.trace.metadata.workflowName`。

如要將 evaluator 的範圍限定於特定 Agent，請在 Langfuse 設定以下其中一項篩選條件：

- **Trace 名稱**：等於 Agent 名稱（例如 `weather-agent`）。
- **Metadata**：`agentId` 等於 Agent id。

Langfuse evaluator 篩選器中的 Trace 名稱下拉式選單會列出曾出現的每個相異值，因此每個 Agent 只要產生過至少一個 Trace，便會顯示為獨立項目。

如你透過 `mastra.metadata.traceName` 設定自訂 `traceName`，你的值會優先於預設的 Agent 名稱。

## 自訂 Trace metadata

Langfuse 只會按最上層 metadata 篩選及分組 Trace，無法使用巢狀 metadata key 進行篩選或分組。

如要加入自己的最上層 metadata，請在 span metadata 的 `langfuse` 下設定 key。Exporter 會將每個 key 轉送至 `langfuse.trace.metadata.<key>`，使其可在 Langfuse 中用作篩選條件：

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

此範例會產生 `langfuse.trace.metadata.customerId` 及 `langfuse.trace.metadata.tier`。

注意：

- 保留的 `prompt` key 用於[連結 prompt](#prompt-linking)，不會作為 Trace metadata 轉送。
- 保留的身分 key `agentId`、`agentName`、`workflowId` 及 `workflowName` 會根據根 span 設定，並優先於同名的自訂值。
- 由於 Langfuse 會將 Trace metadata attribute 對應為字串，因此值會以字串傳送。數字、布林值及物件會使用 JSON 序列化。Langfuse Cloud 在擷取時會將它們還原為原有類型。

## 連結 prompt

你可以將 LLM generation 連結至儲存在 [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 的 `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 會自動將該 generation 連結至相應的 prompt。

## 相關內容

- [Trace 概覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)
- [Langfuse 文件](https://langfuse.com/docs)
- [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management)