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

# Langfuse 수출업체

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

## 설치

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

### 제로 구성 설정

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

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

#### 실시간 모드(개발)

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

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

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

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

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에서 필터링할 수 있습니다.

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

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

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

## Prompt 연결

LLM 생성을 [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management)에 저장된 Prompt에 연결할 수 있습니다. 이를 통해 Prompt의 버전을 추적하고 측정항목을 확인할 수 있습니다.

### 도우미 사용(권장)

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

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

## 관련된

- [추적 개요](https://mastra.zisheng.pro/ko/docs/observability/tracing/overview)
- [랭퓨즈 문서](https://langfuse.com/docs)
- [Langfuse Prompt 관리](https://langfuse.com/docs/prompt-management)