LangfuseExporter

Envoie les données de Tracing à Langfuse à des fins d'observabilité.

Constructeur

new LangfuseExporter(config: LangfuseExporterConfig)

LangfuseExporterConfig

interface LangfuseExporterConfig extends BaseExporterConfig {
  publicKey?: string
  secretKey?: string
  baseUrl?: string
  realtime?: boolean
  flushAt?: number
  flushInterval?: number
  environment?: string
  release?: string
}

Étend BaseExporterConfig, qui comprend :

• logger?: IMastraLogger - Instance du Logger
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Niveau de journalisation (par défaut : INFO)

Propriétés

client

get client(): LangfuseClient | undefined

Instance LangfuseClient destinée aux fonctionnalités Langfuse avancées. Renvoie undefined lorsque l'Exporter est désactivé (identifiants manquants). Utilisez-la pour gérer les prompts, les évaluations et les Datasets, ainsi que pour accéder directement à l'API.

Méthodes

flush

async flush(): Promise<void>

Force l'envoi à Langfuse de tous les spans et scores en mémoire tampon sans arrêter l'Exporter. Cette méthode est utile dans les environnements sans serveur où vous devez vous assurer que les données sont exportées avant la fin de l'environnement d'exécution.

shutdown

async shutdown(): Promise<void>

Envoie les données en attente et arrête le Processor de spans ainsi que le client.

Utilisation

Sans configuration (au moyen de variables d'environnement)

import { LangfuseExporter } from '@mastra/langfuse'

// Reads from LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
const exporter = new LangfuseExporter()

Configuration explicite

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

Mappage des spans

Les spans Mastra sont convertis au format OTel et envoyés à Langfuse au moyen de LangfuseSpanProcessor. Langfuse associe automatiquement les spans selon leurs attributs gen_ai.* :

• Spans dotés d'un attribut model → générations Langfuse
• Tous les autres spans → spans Langfuse
• Les relations parent-enfant sont conservées au moyen des identifiants de Trace/span OTel

Association des prompts

Associez les générations du LLM à la gestion des prompts Langfuse au moyen de la fonction utilitaire withLangfusePrompt :

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

Fonctions utilitaires

withLangfusePrompt(prompt)

Ajoute les métadonnées du prompt Langfuse aux options de Tracing.

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

Les métadonnées du prompt sont transmises comme attributs de span, et Langfuse associe la génération au prompt correspondant.