Langfuse 수출업체

랭퓨즈LLM 애플리케이션을 위해 특별히 설계된 오픈 소스 관찰 플랫폼입니다. Langfuse 내보내기는 추적을 Langfuse로 보내 Model 성능, 토큰 사용, 대화 흐름에 대한 자세한 통찰력을 제공합니다.

설치

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 설정 → 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

제로 구성 설정

환경 변수가 설정된 경우 구성 없이 내보내기를 사용합니다.

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 내보내기는 추적 전송을 위한 두 가지 모드를 지원합니다.

실시간 모드(개발)

디버깅에 이상적인 추적은 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
})

대용량 추적을 위한 일괄 튜닝

초당 많은 범위를 생성하는 자체 호스팅 Langfuse 배포 또는 스트리밍 실행의 경우 OTEL 배치 크기와 플러시 간격을 조정하여 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)을 완전히 억제하려면 Exporter를 설정하는 대신 Observability 수준의 excludeSpanTypes 옵션을 사용하세요.

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당 범위 지정 평가자

Langfuse 평가자(예: 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 이름 WORKFLOW_RUN 루트 Span에도 동일하게 적용되며, 이 경우 langfuse.trace.metadata.workflowId와 langfuse.trace.metadata.workflowName을 설정합니다. 평가자의 범위를 특정 Agent로 지정하려면 Langfuse에서 필터를 구성하세요.
• 추적 이름: Agent 이름과 동일합니다(예: weather-agent).
• 메타데이터: agentId는 Agent ID와 동일합니다. Langfuse 평가기 필터의 추적 이름 드롭다운에는 표시되는 모든 고유 값이 나열되므로 각 Agent는 최소한 하나의 추적을 생성하면 자체 항목으로 표시됩니다.

mastra.metadata.traceName을 통해 traceName을 사용자 지정하면 지정한 값이 기본 Agent 이름보다 우선합니다.

커스텀 추적 메타데이터

Langfuse는 최상위 메타데이터로만 추적을 필터링하고 그룹화합니다. 중첩된 메타데이터 키는 필터링이나 그룹화에 사용할 수 없습니다.

사용자 지정 최상위 메타데이터를 추가하려면 스팬 메타데이터의 langfuse 아래에 키를 설정하세요. 내보내기는 각 키를 langfuse.trace.metadata.<key>로 전달하며, Langfuse에서 필터링할 수 있습니다.

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

이 예제에서는 langfuse.trace.metadata.customerId와 langfuse.trace.metadata.tier가 생성됩니다. 참고:

• 예약된 prompt 키는 Prompt 연결에 사용되며 Trace 메타데이터로 전달되지 않습니다.
• 예약된 ID 키인 agentId, agentName, workflowId, workflowName은 루트 스팬에서 설정되며, 같은 이름의 사용자 지정 값보다 우선합니다.
• Langfuse는 Trace 메타데이터 속성을 문자열로 매핑하므로 값은 문자열로 전송됩니다. 숫자, 부울 및 객체는 JSON으로 직렬화됩니다. Langfuse Cloud는 수집 시 원래 유형으로 복원합니다.

Prompt 연결

LLM 생성을 Langfuse Prompt Management에 저장된 Prompt에 연결할 수 있습니다. 이를 통해 Prompt의 버전을 추적하고 측정항목을 확인할 수 있습니다.

도우미 사용(권장)

가장 깔끔한 API를 사용하려면 withLangfusePrompt를 buildTracingOptions와 함께 사용하세요.

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 헬퍼는 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 스팬에 설정하면 Langfuse 내보내기가 해당 생성을 관련 Prompt에 자동으로 연결합니다.

관련된

• 추적 개요
• 랭퓨즈 문서
• Langfuse Prompt 관리