> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # MastraPlatformExporter **Ajouté dans :** `@mastra/observability@1.12.0`. Les versions antérieures (de `@mastra/observability@1.8.0` à `1.11.x`) exportent le même exportateur sous le nom de `CloudExporter`, désormais obsolète. Envoie des spans de traçage, des journaux, des métriques, des scores et des retours à la plateforme Mastra pour la visualisation et la surveillance en ligne. > **Remarque:** `MastraPlatformExporter` portait auparavant le nom de `CloudExporter`. La classe `CloudExporter` d’origine est toujours exportée depuis `@mastra/observability` afin que les importations existantes continuent de fonctionner, mais elle est obsolète et sera supprimée dans une prochaine version majeure. Le nouveau code doit utiliser `MastraPlatformExporter`. ## Constructeur ```typescript new MastraPlatformExporter(config?: MastraPlatformExporterConfig) ``` ## `MastraPlatformExporterConfig` ```typescript interface MastraPlatformExporterConfig extends BaseExporterConfig { /** Maximum number of buffered events per batch (spans, logs, metrics, scores, feedback). Default: 1000 */ maxBatchSize?: number /** Maximum wait time before flushing in milliseconds. Default: 5000 */ maxBatchWaitMs?: number /** Maximum retry attempts. Default: 3 */ maxRetries?: number /** Mastra Observability access token (from env or config) */ accessToken?: string /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */ projectId?: string /** Base observability endpoint */ endpoint?: string /** Explicit traces endpoint override */ tracesEndpoint?: string /** Explicit logs endpoint override */ logsEndpoint?: string /** Explicit metrics endpoint override */ metricsEndpoint?: string /** Explicit scores endpoint override */ scoresEndpoint?: string /** Explicit feedback endpoint override */ feedbackEndpoint?: string } ``` Étend `BaseExporterConfig`, qui inclut : - `logger?: IMastraLogger` - Instance de journaliseur - `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Niveau de journalisation (par défaut : INFO) ## Variables d’environnement L’exportateur lit ces variables d’environnement si elles ne sont pas fournies dans la configuration : - `MASTRA_PLATFORM_ACCESS_TOKEN` - Jeton d’authentification pour les requêtes de `MastraPlatformExporter` - `MASTRA_PROJECT_ID` - ID de projet à utiliser lors de la dérivation de routes de collecteur limitées au projet, telles que `/projects/:projectId/ai/spans/publish` - `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` - Remplacement du point de terminaison d’observabilité. Transmettez une origine de base ou une URL complète de publication des traces. La valeur par défaut est `https://observability.mastra.ai` dans `@mastra/observability@1.9.2` et les versions ultérieures ## Propriétés ```typescript readonly name = 'mastra-platform-exporter'; ``` La classe `CloudExporter` obsolète continue d’utiliser `'mastra-cloud-observability-exporter'` comme `name` pour assurer la rétrocompatibilité. ## Méthodes ### `exportTracingEvent` ```typescript async exportTracingEvent(event: TracingEvent): Promise ``` Traite les événements de traçage pour les exporter vers la plateforme Mastra. Seuls les événements de traçage `SPAN_ENDED` sont exportés. `SPAN_STARTED` et `SPAN_UPDATED` sont ignorés. Les spans correspondants sont mis en mémoire tampon et téléversés vers le point de terminaison des traces lors du prochain vidage. **Renvoie :** `Promise` une fois que l’événement de traçage a été accepté pour la mise en mémoire tampon ou ignoré. ### `onLogEvent` ```typescript async onLogEvent(event: LogEvent): Promise ``` Traite les signaux de journal pour l’exportation. Chaque `LogEvent` transmis à ce gestionnaire est mis en mémoire tampon et exporté vers le point de terminaison des journaux dérivé du point de terminaison de base configuré. Contrairement au traçage, aucun filtrage supplémentaire de l’état des événements n’est appliqué au niveau de `MastraPlatformExporter`. Si l’exportateur est désactivé, cette méthode ne fait rien. **Renvoie :** `Promise` une fois que l’événement de journal a été accepté pour la mise en mémoire tampon. ### `onMetricEvent` ```typescript async onMetricEvent(event: MetricEvent): Promise ``` Traite les signaux de métrique pour l’exportation. Chaque `MetricEvent` transmis à ce gestionnaire est mis en mémoire tampon et exporté vers le point de terminaison des métriques dérivé du point de terminaison de base configuré. Aucun filtrage supplémentaire par sous-type ou état de métrique n’est effectué dans `MastraPlatformExporter`. L’exportateur transfère chaque événement de métrique qu’il reçoit, sauf s’il est désactivé. **Renvoie :** `Promise` une fois que l’événement de métrique a été accepté pour la mise en mémoire tampon. ### `onScoreEvent` ```typescript async onScoreEvent(event: ScoreEvent): Promise ``` Traite les signaux de score pour l’exportation. Chaque `ScoreEvent` transmis à ce gestionnaire est mis en mémoire tampon et exporté vers le point de terminaison des scores dérivé du point de terminaison de base configuré. Aucun filtrage supplémentaire n’est effectué dans la couche d’exportation, au-delà de la vérification que l’exportateur est désactivé ; tous les événements de score reçus par cette méthode sont donc transférés. **Renvoie :** `Promise` une fois que l’événement de score a été accepté pour la mise en mémoire tampon. ### `onFeedbackEvent` ```typescript async onFeedbackEvent(event: FeedbackEvent): Promise ``` Traite les signaux de retour pour l’exportation. Chaque `FeedbackEvent` transmis à ce gestionnaire est mis en mémoire tampon et exporté vers le point de terminaison des retours dérivé du point de terminaison de base configuré. Aucun filtrage par type de retour n’est effectué dans `MastraPlatformExporter`. Tous les événements de retour reçus ici sont transférés, sauf si l’exportateur est désactivé. **Renvoie :** `Promise` une fois que l’événement de retour a été accepté pour la mise en mémoire tampon. ### flush ```typescript async flush(): Promise ``` Force le vidage de tous les événements en mémoire tampon vers la plateforme Mastra sans arrêter l’exportateur. Utile dans les environnements serverless, où vous devez vous assurer que les spans sont exportés avant l’arrêt de l’exécution. ### shutdown ```typescript async shutdown(): Promise ``` Vide les événements restants et effectue le nettoyage. ## Comportement ### Authentification Si aucun jeton d’accès n’est fourni par la configuration ou une variable d’environnement, l’exportateur : - Enregistre un avertissement contenant des informations d’inscription - Ne fait rien (ignore tous les événements) ### Traitement par lots L’exportateur regroupe les spans de traçage, les journaux, les métriques, les scores et les retours par lots afin d’utiliser le réseau efficacement : - Vide le tampon lorsque le nombre total d’événements mis en mémoire tampon atteint `maxBatchSize` - Vide le tampon lorsque `maxBatchWaitMs` se sont écoulées depuis le premier signal mis en mémoire tampon du lot - Vide le tampon lors de `shutdown()` ### Gestion des erreurs - Utilise des nouvelles tentatives avec temporisation exponentielle, jusqu’à `maxRetries` tentatives - Abandonne les lots après l’échec de toutes les tentatives - Enregistre les erreurs tout en continuant à traiter les nouveaux événements Les erreurs levées par `MastraPlatformExporter` utilisent le préfixe `MASTRA_PLATFORM_EXPORTER_*` pour leur `id`. `CloudExporter`, désormais obsolète, continue d’émettre des `CLOUD_EXPORTER_*` comme `id`. ### Routage des points de terminaison - Les origines de base dérivent automatiquement les points de terminaison des signaux - Sans `projectId`, les routes dérivées utilisent `/ai/{signal}/publish` - Avec `projectId` ou `MASTRA_PROJECT_ID`, les routes dérivées utilisent `/projects/:projectId/ai/{signal}/publish` - Les URL complètes de publication explicites sont utilisées telles quelles, même lorsque `projectId` est configuré ### Traitement des signaux - `exportTracingEvent()` exporte uniquement les événements de traçage `SPAN_ENDED` - `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()` et `onFeedbackEvent()` mettent en mémoire tampon chaque événement qu’ils reçoivent pour leur type de signal respectif - Tous les lots de signaux pris en charge sont téléversés vers leurs points de terminaison de publication correspondants pendant `flush()` et `shutdown()` ## Format de transport des spans La forme de chaque span envoyé à la plateforme Mastra est documentée ici uniquement à titre de référence : elle n’est pas exportée depuis `@mastra/observability` et ne doit pas être importée. L’exportateur étale l’`AnyExportedSpan` d’origine (afin de préserver les noms de champs sources) et ajoute par-dessus un petit ensemble d’alias adaptés à la plateforme : ```typescript type MastraPlatformSpanRecord = AnyExportedSpan & { // Aliases derived from the source span spanId: string // alias for span.id spanType: string // alias for span.type startedAt: Date // alias for span.startTime endedAt: Date | null // alias for span.endTime ?? null error: AnyExportedSpan['errorInfo'] | null // Stamped at export time createdAt: Date updatedAt: Date | null } ``` L’`AnyExportedSpan` étalé contient aussi les champs d’origine `id`, `type`, `name`, `traceId`, `parentSpanId`, `isRootSpan`, `isEvent`, `startTime`, `endTime`, `entityType`, `entityId`, `entityName`, `tags`, `attributes`, `metadata`, `input`, `output` et `errorInfo`. Consultez [Interfaces](https://mastra.zisheng.pro/fr/reference/observability/tracing/interfaces) pour `AnyExportedSpan`. ## Utilisation ```typescript import { MastraPlatformExporter } from '@mastra/observability' // Uses environment variable for token const exporter = new MastraPlatformExporter() // Explicit configuration const customExporter = new MastraPlatformExporter({ accessToken: 'your-token', projectId: 'project_123', maxBatchSize: 500, maxBatchWaitMs: 2000, logLevel: 'debug', }) ``` ## Migration depuis `CloudExporter` Les deux classes partagent la même signature de constructeur, les mêmes variables d’environnement et le même comportement. Pour migrer, remplacez l’importation et le constructeur : ```typescript // Before import { CloudExporter } from '@mastra/observability' const exporter = new CloudExporter() // After import { MastraPlatformExporter } from '@mastra/observability' const exporter = new MastraPlatformExporter() ``` Le `CloudExporter` d’origine est préservé tel quel afin que les tableaux de bord ou les règles d’alerte correspondant aux anciens ID d’erreur `CLOUD_EXPORTER_*` ou au nom d’exportateur `mastra-cloud-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 - [Exportateurs](https://mastra.zisheng.pro/fr/docs/observability/integrations/overview): Concepts d’exportateurs ### Autres exportateurs - [MastraStorageExporter](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/mastra-storage-exporter): Persistance dans le stockage - [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 Langfuse - [Braintrust](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/braintrust): Intégration 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