MastraStorageExporter

Conserve les traces dans le stockage configuré de Mastra avec une logique automatique de traitement par lots et de nouvelle tentative.

remarque

MastraStorageExporter s'appelait auparavant DefaultExporter. La classe DefaultExporter d'origine reste exportée depuis @mastra/observability afin que les imports existants continuent de fonctionner, mais elle est obsolète et sera supprimée dans une prochaine version majeure. Tout nouveau code doit utiliser MastraStorageExporter.

Constructeur

new MastraStorageExporter(config?: MastraStorageExporterConfig)

MastraStorageExporterConfig

interface MastraStorageExporterConfig 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 de logger
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Niveau de journalisation (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-storage-exporter';

Pour assurer la rétrocompatibilité, la classe obsolète DefaultExporter continue d'utiliser 'mastra-default-observability-exporter' comme name.

Méthodes

init

init(options: InitExporterOptions): void

Initialise l'exporteur une fois les dépendances prêtes. Détermine la stratégie de traçage en fonction des capacités du stockage.

exportTracingEvent

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

Traite un événement de traçage conformément à la stratégie déterminée.

flush

async flush(): Promise<void>

Force l'écriture dans le stockage de tous les événements mis en mémoire tampon sans arrêter l'exporteur. Cette méthode est utile dans les environnements serverless où vous devez vous assurer que les spans sont exportés avant la fin de l'environnement d'exécution.

shutdown

async shutdown(): Promise<void>

Écrit les événements restants en mémoire tampon et effectue le nettoyage.

Sélection automatique de la stratégie

Lorsque strategy: 'auto' (valeur par défaut), l'exporteur interroge l'adaptateur de stockage sur ses capacités :

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

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

L'exporteur :

1. utilise la stratégie préférée de l'adaptateur de stockage si elle est disponible ;
2. se rabat sur 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 traitement par lots

Déclencheurs de l'écriture

La mémoire tampon est écrite lorsque l'une de ces conditions est remplie :

• sa taille atteint maxBatchSize ;
• le temps écoulé depuis le premier événement mis en mémoire tampon dépasse maxBatchWaitMs ;
• sa taille atteint maxBufferSize (écriture d'urgence) ;
• shutdown() est appelée.

Logique de nouvelle tentative

Les écritures qui échouent sont retentées avec un délai exponentiel :

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

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 fins de spans qui n'ont pas encore été créés ;
• consigne des avertissements pour les événements désordonnés ;
• conserve des numéros de séquence afin d'ordonner les mises à jour.

Utilisation

import { MastraStorageExporter } from '@mastra/observability'

// Default configuration
const exporter = new MastraStorageExporter()

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

Migrer depuis DefaultExporter

Les deux classes partagent la même signature de constructeur et le même comportement. Pour migrer, remplacez l'import et le constructeur :

// Before
import { DefaultExporter } from '@mastra/observability'
const exporter = new DefaultExporter()

// After
import { MastraStorageExporter } from '@mastra/observability'
const exporter = new MastraStorageExporter()

La classe DefaultExporter d'origine est conservée sans modification afin que les tableaux de bord ou les règles d'alerte correspondant à l'ancien nom d'exporteur mastra-default-observability-exporter continuent de fonctionner jusqu'à votre migration.

Voir aussi

Documentation

• Présentation du traçage : guide complet
• Exporteurs : concepts liés aux exporteurs

Autres exporteurs

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

Référence

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