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

# 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

```typescript
new MastraStorageExporter(config?: MastraStorageExporterConfig)
```

## `MastraStorageExporterConfig`

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

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

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

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

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

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

### flush

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

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

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

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

```typescript
// 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](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : guide complet
- [Exporteurs](https://mastra.zisheng.pro/fr/docs/observability/integrations/overview) : concepts liés aux exporteurs

### Autres exporteurs

- [MastraPlatformExporter](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/mastra-platform-exporter) : plateforme Mastra
- [ConsoleExporter](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/console-exporter) : sortie de débogage
- [Langfuse](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/langfuse) : intégration de Langfuse
- [Braintrust](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/braintrust) : intégration de Braintrust

### Référence

- [Configuration](https://mastra.zisheng.pro/fr/reference/observability/tracing/configuration) : options de configuration
- [Interfaces](https://mastra.zisheng.pro/fr/reference/observability/tracing/interfaces) : définitions de types