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

# LangfuseExporter

將 Tracing 數據傳送至 Langfuse，以便進行可觀測性監察。

## 建構函數

```typescript
new LangfuseExporter(config: LangfuseExporterConfig)
```

## `LangfuseExporterConfig`

```typescript
interface LangfuseExporterConfig extends BaseExporterConfig {
  publicKey?: string
  secretKey?: string
  baseUrl?: string
  realtime?: boolean
  flushAt?: number
  flushInterval?: number
  environment?: string
  release?: string
}
```

擴充 `BaseExporterConfig`，當中包括：

- `logger?: IMastraLogger` - Logger 實例
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - 日誌層級（預設：INFO）

## 屬性

### `client`

```typescript
get client(): LangfuseClient | undefined
```

用於 Langfuse 進階功能的 `LangfuseClient` 實例。當 exporter 因缺少憑證而停用時，會傳回 `undefined`。你可使用此實例管理 prompt、進行評估、處理數據集，以及直接存取 API。

## 方法

### flush

```typescript
async flush(): Promise<void>
```

強制將所有已緩衝的 span 和分數清空並傳送至 Langfuse，而不會關閉 exporter。這適用於 serverless 環境，讓你可確保數據在 runtime 終止前已匯出。

### shutdown

```typescript
async shutdown(): Promise<void>
```

清空並傳送待處理數據，然後關閉 span processor 和 client。

## 使用方式

### 零設定（使用環境變數）

```typescript
import { LangfuseExporter } from '@mastra/langfuse'

// Reads from LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
const exporter = new LangfuseExporter()
```

### 明確設定

```typescript
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 對應

Mastra span 會轉換為 OTel 格式，並透過 `LangfuseSpanProcessor` 傳送至 Langfuse。Langfuse 會根據 span 的 `gen_ai.*` 屬性自動進行對應：

- 具有 `model` 屬性的 span → Langfuse generation
- 所有其他 span → Langfuse span
- 父子關係會透過 OTel trace/span ID 保留

## Prompt 連結

使用 `withLangfusePrompt` 輔助函式，將 LLM generation 連結至 [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management)：

```typescript
import { buildTracingOptions } from '@mastra/observability'
import { LangfuseExporter, withLangfusePrompt } from '@mastra/langfuse'

const exporter = new LangfuseExporter()

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

const agent = new Agent({
  id: 'support-agent',
  name: 'support-agent',
  instructions: prompt.compile(),
  model: 'openai/gpt-5.6-sol',
  defaultGenerateOptions: {
    tracingOptions: buildTracingOptions(
      withLangfusePrompt({ name: prompt.name, version: prompt.version }),
    ),
  },
})
```

### 輔助函式

#### `withLangfusePrompt(prompt)`

將 Langfuse prompt metadata 加至 tracing 選項。

```typescript
// Link by name and version (required for Langfuse v5)
withLangfusePrompt({ name: 'my-prompt', version: 1 })
```

prompt metadata 會以 span 屬性傳遞，而 Langfuse 會將 generation 連結至相應 prompt。