DefaultExporter

Obsolète depuis @mastra/observability@1.12.0 au profit de MastraStorageExporter.

Obsolète

DefaultExporter est conservé à des fins de rétrocompatibilité et sera supprimé dans une prochaine version majeure. Utilisez MastraStorageExporter pour les nouveaux projets. Les deux classes partagent le même constructeur, la même configuration et le même comportement à l’exécution. DefaultExporter conserve son identifiant d’exportateur d’origine mastra-default-observability-exporter dans name, afin que les règles de supervision qui reposent dessus continuent de fonctionner.

Conserve les événements d’observabilité dans le stockage Mastra avec regroupement automatique par lots et logique de nouvelle tentative.

Constructeur

new DefaultExporter(config?: DefaultExporterConfig)

DefaultExporterConfig

interface DefaultExporterConfig extends BaseExporterConfig {
  /** Maximum number of spans per batch. Default: 1000 */
  maxBatchSize?: number

  /** Maximum total buffer size before emergency flush. Default: 10000 */
  maxBufferSize?: number

  /** Maximum time to wait before flushing batch in milliseconds. Default: 5000 */
  maxBatchWaitMs?: number

  /** Maximum number of retry attempts. Default: 4 */
  maxRetries?: number

  /** Base retry delay in milliseconds (uses exponential backoff). Default: 500 */
  retryDelayMs?: number

  /** Tracing storage strategy or 'auto' for automatic selection. Default: 'auto' */
  strategy?: TracingStorageStrategy | 'auto'
}

Étend BaseExporterConfig, qui comprend :

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

TracingStorageStrategy

type TracingStorageStrategy = 'realtime' | 'batch-with-updates' | 'insert-only'

Comportement des stratégies

• realtime : conserve immédiatement chaque événement dans le stockage
• batch-with-updates : regroupe séparément les créations et les mises à jour, puis les applique dans l’ordre
• insert-only : traite uniquement les événements SPAN_ENDED et ignore les mises à jour

Propriétés

readonly name = 'mastra-default-observability-exporter';

Méthodes

init

init(options: InitExporterOptions): void

Initialise l’exportateur une fois les dépendances prêtes. Résout la stratégie de tracing selon les capacités du stockage.

exportTracingEvent

async exportTracingEvent(event: TracingEvent): Promise<void>

Traite un événement de tracing selon la stratégie résolue.

flush

async flush(): Promise<void>

Force l’envoi vers le stockage de tous les événements mis en mémoire tampon sans arrêter l’exportateur. Cette méthode est utile dans les environnements serverless où vous devez vous assurer que les spans sont exportés avant l’arrêt du runtime.

shutdown

async shutdown(): Promise<void>

Envoie les événements encore présents en mémoire tampon et effectue le nettoyage.

Sélection automatique de la stratégie

Lorsque strategy: 'auto' est utilisé (valeur par défaut), l’exportateur interroge l’adaptateur de stockage pour connaître ses capacités :

interface TracingStrategy {
  /** Strategies supported by this adapter */
  supported: TracingStorageStrategy[]

  /** Preferred strategy for optimal performance */
  preferred: TracingStorageStrategy
}

L’exportateur effectue les opérations suivantes :

1. Utilise la stratégie préférée de l’adaptateur de stockage si elle est disponible
2. Utilise à défaut la première stratégie prise en charge si la stratégie préférée n’est pas disponible
3. Consigne un avertissement si une stratégie indiquée par l’utilisateur n’est pas prise en charge

Comportement du regroupement par lots

Déclencheurs du flush

Le tampon est envoyé lorsque l’une des conditions suivantes est remplie :

• La taille du tampon atteint maxBatchSize
• Le temps écoulé depuis le premier événement mis en mémoire tampon dépasse maxBatchWaitMs
• La taille du tampon atteint maxBufferSize (flush d’urgence)
• shutdown() est appelée

Logique de nouvelle tentative

Les flushs qui échouent sont retentés avec un backoff exponentiel :

• Délai avant une nouvelle tentative : retryDelayMs * 2^attempt
• Nombre maximal de tentatives : maxRetries
• Le lot est abandonné après l’échec de toutes les tentatives

Lorsque le stockage ne prend pas en charge un signal ou que toutes les nouvelles tentatives sont épuisées, DefaultExporter émet un ObservabilityDropEvent par l’intermédiaire des gestionnaires onDroppedEvent enregistrés sur les exportateurs et les bridges. L’événement d’abandon comprend le signal, la raison, le nombre, le nom de l’exportateur, le nom du stockage lorsqu’il est connu et les détails assainis de l’erreur.

Gestion des événements désordonnés

Pour la stratégie batch-with-updates :

• Suit les spans qui ont été créés
• Rejette les mises à jour et les fins de spans qui n’ont pas encore été créés
• Consigne des avertissements pour les événements désordonnés
• Conserve les numéros de séquence afin d’ordonner les mises à jour

Utilisation

import { DefaultExporter } from '@mastra/observability'

// Default configuration
const exporter = new DefaultExporter()

// Custom batching configuration
const customExporter = new DefaultExporter({
  maxBatchSize: 500,
  maxBatchWaitMs: 2000,
  strategy: 'batch-with-updates',
  logLevel: 'debug',
})

Voir aussi

Documentation

• Présentation du tracing : guide complet
• Exportateurs : concepts des exportateurs

Autres exportateurs

• CloudExporter : plateforme Mastra
• ConsoleExporter : sortie de débogage
• Langfuse : intégration à Langfuse
• Braintrust : intégration à Braintrust

Référence

• Configuration : options de configuration
• Interfaces : définitions de types