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

# Exporter Langfuse

[Langfuse](https://langfuse.com/) est une plateforme d’observabilité open source spécialement conçue pour les applications fondées sur des LLM. L’exporter Langfuse envoie vos traces à Langfuse et fournit des informations détaillées sur les performances des modèles, l’utilisation des tokens et les flux de conversation.

## Installation

**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
```

## Configuration

### Prérequis

1. **Compte Langfuse** : inscrivez-vous sur [cloud.langfuse.com](https://cloud.langfuse.com) ou déployez une instance auto-hébergée
2. **Clés d’API** : créez une paire de clés publique/secrète dans Settings → API Keys de Langfuse
3. **Variables d’environnement** : définissez vos identifiants

```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
```

### Configuration automatique

Une fois les variables d’environnement définies, utilisez l’exporter sans configuration :

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

### Configuration explicite

Vous pouvez également transmettre les identifiants directement ; ils prévalent sur les variables d’environnement :

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

## Options de configuration

### Mode temps réel ou traitement par lots

L’exporter Langfuse propose deux modes d’envoi des traces :

#### Mode temps réel (développement)

Les traces apparaissent immédiatement dans le tableau de bord Langfuse, ce qui est idéal pour le débogage :

```typescript
new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  realtime: true, // Flush after each event
})
```

#### Mode par lots (production)

Le regroupement automatique par lots améliore les performances :

```typescript
new LangfuseExporter({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  realtime: false, // Default - batch traces
})
```

#### Ajustement du traitement par lots pour les volumes élevés de traces

Pour les déploiements Langfuse auto-hébergés ou les exécutions en streaming qui produisent de nombreux spans par seconde, vous pouvez ajuster la taille des lots OTEL et l’intervalle d’envoi afin de réduire la pression des requêtes sur le point de terminaison d’ingestion de 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
})
```

Pour exclure entièrement les types de spans générés en grand nombre (par exemple, les spans `MODEL_CHUNK` issus de réponses en streaming), utilisez [l’option `excludeSpanTypes`](https://mastra.zisheng.pro/fr/reference/observability/tracing/span-filtering) au niveau de l’observabilité plutôt que de configurer l’exporter :

```typescript
import { SpanType } from '@mastra/core/observability'

new Observability({
  configs: {
    langfuse: {
      serviceName: 'my-service',
      exporters: [new LangfuseExporter()],
      excludeSpanTypes: [SpanType.MODEL_CHUNK],
    },
  },
})
```

### Configuration complète

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

## Limiter les évaluateurs à un Agent

Les évaluateurs Langfuse (tels que LLM-as-a-Judge) peuvent être filtrés afin de ne s’exécuter que sur certaines traces. L’exporter Langfuse de Mastra associe automatiquement chaque trace à l’Agent ou au Workflow qui l’a initiée, afin que les filtres au niveau des traces ciblent les bonnes exécutions.

Pour chaque trace dont le span racine est un `AGENT_RUN`, l’exporter définit :

- `langfuse.trace.name` : le nom de l’Agent (ou son identifiant lorsqu’aucun nom n’est défini)
- `langfuse.trace.metadata.agentId` : l’identifiant de l’Agent
- `langfuse.trace.metadata.agentName` : le nom de l’Agent

Il en va de même pour les spans racines `WORKFLOW_RUN`, qui définissent `langfuse.trace.metadata.workflowId` et `langfuse.trace.metadata.workflowName`.

Pour limiter un évaluateur à un Agent précis, configurez l’un des filtres suivants dans Langfuse :

- **Nom de la trace** : correspond au nom de l’Agent (par exemple, `weather-agent`).
- **Métadonnées** : `agentId` correspond à l’identifiant de l’Agent.

La liste déroulante des noms de traces dans les filtres des évaluateurs Langfuse répertorie chaque valeur distincte rencontrée. Chaque Agent apparaît donc comme une entrée distincte dès qu’il a produit au moins une trace.

Si vous définissez un `traceName` personnalisé au moyen de `mastra.metadata.traceName`, votre valeur prévaut sur le nom par défaut de l’Agent.

## Métadonnées de trace personnalisées

Langfuse filtre et regroupe les traces uniquement à partir des métadonnées de premier niveau. Les clés de métadonnées imbriquées ne peuvent pas servir au filtrage ni au regroupement.

Pour ajouter vos propres métadonnées de premier niveau, définissez des clés sous `langfuse` dans les métadonnées de votre span. L’exporter transmet chaque clé à `langfuse.trace.metadata.<key>`, ce qui permet ensuite de la filtrer dans Langfuse :

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

Cet exemple produit `langfuse.trace.metadata.customerId` et `langfuse.trace.metadata.tier`.

Remarques :

- La clé réservée `prompt` sert à [associer les prompts](#prompt-linking) et n’est pas transmise en tant que métadonnée de trace.
- Les clés d’identité réservées `agentId`, `agentName`, `workflowId` et `workflowName` sont définies à partir du span racine et prévalent sur les valeurs personnalisées portant le même nom.
- Les valeurs sont envoyées sous forme de chaînes de caractères, car Langfuse représente les attributs des métadonnées de trace comme des chaînes. Les nombres, les booléens et les objets sont sérialisés au format JSON. Langfuse Cloud rétablit leur type d’origine lors de l’ingestion.

## Association des prompts

Vous pouvez associer les générations de LLM aux prompts stockés dans [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management). Vous bénéficiez ainsi du suivi des versions et de métriques pour vos prompts.

### Utiliser la fonction d’assistance (recommandé)

Utilisez `withLangfusePrompt` avec `buildTracingOptions` pour obtenir l’API la plus claire :

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

La fonction d’assistance `withLangfusePrompt` accepte les champs `name` et `version` pour associer les prompts. Langfuse v5 exige ces deux champs.

### Champs manuels

Vous pouvez également transmettre les champs manuellement si vous n’utilisez pas le SDK Langfuse :

```typescript
const tracingOptions = buildTracingOptions(withLangfusePrompt({ name: 'my-prompt', version: 1 }))
```

### Champs de l’objet prompt

L’objet prompt exige à la fois `name` et `version` :

| Champ     | Type   | Description                 |
| --------- | ------ | --------------------------- |
| `name`    | string | Nom du prompt dans Langfuse |
| `version` | number | Numéro de version du prompt |

Lorsque ces champs sont définis sur un span `MODEL_GENERATION`, l’exporter Langfuse associe automatiquement la génération au prompt correspondant.

## Voir aussi

- [Présentation du tracing](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview)
- [Documentation de Langfuse](https://langfuse.com/docs)
- [Gestion des prompts dans Langfuse](https://langfuse.com/docs/prompt-management)