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 金鑰：在 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 dashboard，適合用於除錯：

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

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 的範圍限定於啟動該 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 名稱：等於 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 中用作篩選條件：

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

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

注意：

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

連結 prompt

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

相關內容

• Trace 概覽
• Langfuse 文件
• Langfuse Prompt Management