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

# Langfuse수출업체

Observability을 위해 추적 데이터를 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`- 로거 인스턴스
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'`- 로그 수준(기본값: INFO)

## 속성

### `client`

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

고급 Langfuse 기능을 위한 `LangfuseClient` 인스턴스입니다. exporter가 비활성화되어 있으면(자격 증명 누락) `undefined`를 반환합니다. Prompt 관리, 평가, 데이터세트, 직접 API 액세스에 사용하세요.

## 행동 양식

### 플러시

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

Force는 종료하지 않고 버퍼링된 모든 범위와 점수를 Langfuse로 플러시합니다. 런타임이 종료되기 전에 데이터를 내보내야 하는 서버리스 환경에 유용합니다.

### 일시 휴업

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

보류 중인 데이터를 플러시하고 스팬 프로세서와 클라이언트를 모두 종료합니다.

## 용법

### Zero-Config(환경 변수 사용)

```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,
})
```

## 스팬 매핑

Mastra span은 Otel 형식으로 변환된 후 `LangfuseSpanProcessor`를 통해 Langfuse로 전송됩니다. Langfuse는 `gen_ai.*` 속성에 따라 span을 자동으로 매핑합니다.

- 다음을 포함하는 스팬`model` attribute → Langfuse generations
- 기타 모든 스팬 → Langfuse 스팬
- 상위-하위 관계는 Otel 추적/스팬 ID를 통해 보존됩니다.

## Prompt 연결

`withLangfusePrompt` 헬퍼를 사용하여 LLM 생성을 [Langfuse Prompt 관리](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 메타데이터를 추가합니다.

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

Prompt 메타데이터는 범위 속성으로 전달되고 Langfuse는 생성을 해당 Prompt에 연결합니다.