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

# Exportateur Mastra Platform

`MastraPlatformExporter` envoie les traces, journaux, métriques, scores et retours à Mastra Platform. Utilisez-le pour router les données d’observabilité de n’importe quelle application Mastra vers un projet hébergé sur Mastra Platform.

> **Remarque:** `MastraPlatformExporter` s’appelait auparavant `CloudExporter`. La classe `CloudExporter` d’origine est toujours exportée depuis `@mastra/observability` pour assurer la rétrocompatibilité, mais elle est obsolète. Le nouveau code doit utiliser `MastraPlatformExporter`.

> **Applications auto-hébergées ou autonomes:** Si vous hébergez votre application Mastra sur votre propre infrastructure, et non sur Mastra Platform, vous avez toujours besoin d’un projet Studio déployé pour consulter les traces, journaux et métriques. `MastraPlatformExporter` envoie les données à un projet Studio ; celui-ci doit donc exister avant que vous puissiez l’utiliser.
>
> 1. [Créez un projet Mastra](https://mastra.zisheng.pro/fr/guides/getting-started/quickstart) si vous n’en avez pas encore.
> 2. [Déployez Studio](https://mastra.zisheng.pro/fr/docs/studio/deployment) sur Mastra Platform avec `mastra studio deploy`.
> 3. Suivez les [étapes de démarrage rapide ci-dessous](#quickstart) pour créer un token d’accès et trouver l’identifiant de votre projet.

## Compatibilité des versions

- `MastraPlatformExporter` est disponible à partir de `@mastra/observability@1.12.0`. Entre `1.8.0` et `1.11.x`, le même exportateur est disponible uniquement sous le nom `CloudExporter`. La signature du constructeur et les variables d’environnement sont identiques.
- De `@mastra/observability@1.8.0` à `1.9.1`, définissez `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai` en plus de `MASTRA_PLATFORM_ACCESS_TOKEN` et `MASTRA_PROJECT_ID`.
- À partir de `@mastra/observability@1.9.2`, l’exportateur utilise par défaut `https://observability.mastra.ai`. `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` n’est donc nécessaire que si vous souhaitez envoyer la télémétrie à un autre collecteur.

## Démarrage rapide

Pour connecter `MastraPlatformExporter`, créez un token d’accès, trouvez le `projectId` de destination et ajoutez l’exportateur à votre configuration d’observabilité.

### 1. Créer un token d’accès

Exécutez la commande suivante :

```bash
mastra auth tokens create exporter-token
```

Cette commande affiche un token secret que vous pouvez utiliser comme `MASTRA_PLATFORM_ACCESS_TOKEN`.

Si vous possédez déjà un token d’accès, copiez plutôt la valeur **Observabilité** depuis Mastra Platform. Vous la trouverez à l’un des emplacements suivants :

- Sur la page **Projets**, ouvrez la liste des projets et recherchez la ligne **Observabilité** sur la carte du projet.
- Sur la page **Vue d’ensemble** du projet, recherchez la ligne **Observabilité** directement sous l’URL de déploiement.

Définissez le token comme variable d’environnement :

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
```

### 2. Trouver votre `projectId`

Exécutez la commande suivante :

```bash
mastra studio deploy list
```

La sortie ressemble à ceci :

```text
✅ <your-project-name> (<your-project-id>)
   Latest:   00000000-0000-0000-0000-000000000000 — running
   URL:      https://260407.studio.mastra.cloud
```

Dans cette sortie, la valeur entre parenthèses est le `projectId` :

```text
<your-project-id>
```

Définissez-le comme variable d’environnement :

```bash
MASTRA_PROJECT_ID=<your-project-id>
```

### 3. Définir vos variables d’environnement

Définissez les deux valeurs dans votre environnement afin que `MastraPlatformExporter` puisse s’authentifier et router la télémétrie vers le bon projet :

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=<your-platform-access-token>
MASTRA_PROJECT_ID=<your-project-id>
```

Si vous utilisez une version comprise entre `@mastra/observability@1.8.0` et `1.9.1`, définissez également explicitement le collecteur Mastra Platform :

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://observability.mastra.ai
```

Si vous souhaitez envoyer la télémétrie ailleurs que vers Mastra Platform, définissez également `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`. Transmettez soit une origine de base, soit une URL complète de publication des traces se terminant par `/spans/publish`.

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
```

Lorsque vous transmettez une origine de base, `MastraPlatformExporter` déduit automatiquement les URL de publication correspondantes pour les traces, journaux, métriques, scores et retours.

### 4. Activer `MastraPlatformExporter`

L’exemple suivant montre comment ajouter `MastraPlatformExporter` à votre configuration d’observabilité :

```ts
import { Mastra } from '@mastra/core'
import { Observability, MastraPlatformExporter } from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      production: {
        serviceName: 'api-server',
        exporters: [new MastraPlatformExporter()],
      },
    },
  }),
})
```

Définissez `serviceName` dans la configuration d’observabilité, et non dans `MastraPlatformExporter` lui-même.

Utilisez une valeur `serviceName` stable. Dans Studio, vous pouvez filtrer les traces par **Déploiements → Nom du service** ; un nom cohérent facilite donc leur recherche.

Consultez la [référence de la configuration d’observabilité](https://mastra.zisheng.pro/fr/reference/observability/tracing/configuration) pour découvrir la structure complète de cette configuration.

Si vous préférez, vous pouvez vous appuyer entièrement sur les variables d’environnement :

```ts
new MastraPlatformExporter()
```

Lorsque `MASTRA_PLATFORM_ACCESS_TOKEN` et `MASTRA_PROJECT_ID` sont définis, `MastraPlatformExporter` envoie les données au projet Mastra Platform que vous avez configuré. Si vous définissez également `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`, il les envoie à ce collecteur à la place. Consultez la [référence de MastraPlatformExporter](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/mastra-platform-exporter) pour obtenir la liste complète des options de configuration.

## Configuration recommandée

Incluez `MastraStorageExporter` si vous souhaitez également inspecter les traces locales dans Studio ou conserver les données d’observabilité dans le stockage configuré.

```ts
import { Mastra } from '@mastra/core'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter(), new MastraPlatformExporter()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})
```

## Configuration complète

`MastraPlatformExporter` cible Mastra Platform par défaut. Si vous souhaitez envoyer la télémétrie à un autre collecteur, définissez `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` dans votre environnement ou transmettez `endpoint` dans le code.

```bash
MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT=https://collector.example.com
```

L’exemple suivant montre comment remplacer l’endpoint du collecteur et le comportement de traitement par lots dans le code :

```ts
new MastraPlatformExporter({
  endpoint: 'https://collector.example.com',
  maxBatchSize: 1000,
  maxBatchWaitMs: 5000,
  logLevel: 'info',
})
```

## Consulter les données dans Mastra Studio

Après avoir activé `MastraPlatformExporter`, ouvrez votre projet dans [Mastra Studio](https://projects.mastra.ai) pour inspecter les données exportées.

- Ouvrez le projet auquel vous avez associé `MASTRA_PROJECT_ID`, puis sélectionnez **Ouvrir Studio**.
- Dans Studio, accédez à **Traces** pour inspecter les traces des agents et des workflows.
- Ouvrez le menu de filtrage et utilisez **Déploiements → Nom du service** pour isoler les traces d’une application ou d’un déploiement précis.
- Utilisez la page **Journaux** du tableau de bord du projet pour inspecter les journaux exportés.

Lorsque vous effectuez un déploiement avec Mastra Studio, définissez **Déploiement → Nom du service** sur une valeur stable et veillez à ce qu’elle corresponde au `serviceName` de votre configuration d’observabilité. Il devient ainsi plus facile de filtrer les traces dans Studio au moyen de **Déploiements → Nom du service** lorsque plusieurs services ou déploiements envoient des données au même projet.

## Performances

> **Info:** MastraPlatformExporter utilise le traitement par lots afin d’optimiser l’utilisation du réseau. Les événements sont mis en mémoire tampon et envoyés par lots, ce qui réduit la surcharge tout en maintenant une visibilité presque en temps réel.

### Comportement du traitement par lots

- Les événements sont regroupés par lots jusqu’à `maxBatchSize` (valeur par défaut : 1000).
- Les lots sont envoyés lorsqu’ils sont pleins ou après `maxBatchWaitMs` (valeur par défaut : 5 secondes).
- Les lots ayant échoué sont réessayés avec un délai exponentiel.
- L’exportateur continue de fonctionner de manière dégradée si Mastra Studio est inaccessible.

## Ressources associées

- [Vue d’ensemble du traçage](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview)
- [MastraStorageExporter](https://mastra.zisheng.pro/fr/docs/observability/integrations/exporters/mastra-storage)