Exporter Langfuse

Langfuse 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

npm install @mastra/langfuse@latest

pnpm

pnpm add @mastra/langfuse@latest

Yarn

yarn add @mastra/langfuse@latest

Bun

bun add @mastra/langfuse@latest

Configuration

Prérequis

1. Compte Langfuse : inscrivez-vous sur 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

.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

Configuration automatique

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

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

Configuration explicite

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

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

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 :

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 :

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 :

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 au niveau de l’observabilité plutôt que de configurer l’exporter :

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

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

Configuration complète

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 :

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 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. 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 :

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

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 :

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
• Documentation de Langfuse
• Gestion des prompts dans Langfuse