> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # CloudExporter **Ajouté dans :** `@mastra/observability@1.8.0`. **Obsolète depuis `1.12.0`** au profit de [`MastraPlatformExporter`](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/mastra-platform-exporter). > **Obsolète:** `CloudExporter` est conservé pour assurer la rétrocompatibilité et sera supprimé dans une prochaine version majeure. Utilisez [`MastraPlatformExporter`](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/mastra-platform-exporter) pour les nouveaux projets. Les deux classes partagent le même constructeur, les mêmes variables d'environnement et le même comportement à l'exécution ; `CloudExporter` conserve son nom d'exporter d'origine `mastra-cloud-observability-exporter` dans `name`, ainsi que les ID d'erreur `CLOUD_EXPORTER_*`, afin que les règles de surveillance qui en dépendent continuent de fonctionner. Envoie les spans de traçage, logs, métriques, scores et retours à la plateforme Mastra afin de les visualiser et de les surveiller en ligne. ## Constructeur ```typescript new CloudExporter(config?: CloudExporterConfig) ``` ## `CloudExporterConfig` ```typescript interface CloudExporterConfig extends BaseExporterConfig { /** Maximum number of spans per batch. Default: 1000 */ maxBatchSize?: number /** Maximum wait time before flushing in milliseconds. Default: 5000 */ maxBatchWaitMs?: number /** Maximum retry attempts. Default: 3 */ maxRetries?: number /** Cloud access token (from env or config) */ accessToken?: string /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */ projectId?: string /** Base cloud observability endpoint */ endpoint?: string /** Explicit cloud traces endpoint override */ tracesEndpoint?: string /** Explicit cloud logs endpoint override */ logsEndpoint?: string /** Explicit cloud metrics endpoint override */ metricsEndpoint?: string /** Explicit cloud scores endpoint override */ scoresEndpoint?: string /** Explicit cloud feedback endpoint override */ feedbackEndpoint?: string } ``` Étend `BaseExporterConfig`, qui comprend : - `logger?: IMastraLogger` : instance du logger - `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` : niveau de log (valeur par défaut : INFO) ## Variables d'environnement L'exporter lit les variables d'environnement suivantes si elles ne sont pas fournies dans la configuration : - `MASTRA_PLATFORM_ACCESS_TOKEN` : token d'authentification des requêtes `CloudExporter` - `MASTRA_PROJECT_ID` : ID du projet à utiliser lors de la dérivation de routes de collecte propres 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-cloud-observability-exporter'; ``` ## Méthodes ### `exportTracingEvent` ```typescript async exportTracingEvent(event: TracingEvent): Promise ``` Traite les événements de traçage pour l'export Cloud. Seuls les événements de traçage `SPAN_ENDED` sont exportés. `SPAN_STARTED` et `SPAN_UPDATED` sont ignorés. Les spans correspondants sont placés en mémoire tampon, puis envoyés au point de terminaison des traces Cloud lors du prochain flush. **Renvoie :** `Promise` après acceptation de l'événement de traçage pour sa mise en mémoire tampon ou après son exclusion. ### `onLogEvent` ```typescript async onLogEvent(event: LogEvent): Promise ``` Traite les signaux de log pour l'export Cloud. Chaque `LogEvent` transmis à ce gestionnaire est placé en mémoire tampon et exporté vers le point de terminaison des logs Cloud dérivé du point de terminaison de base configuré. Contrairement au traçage, aucun filtrage supplémentaire selon l'état de l'événement n'est effectué au niveau de `CloudExporter`. Si l'exporter est désactivé, cette méthode n'effectue aucune opération. **Renvoie :** `Promise` après acceptation de l'événement de log pour sa mise en mémoire tampon. ### `onMetricEvent` ```typescript async onMetricEvent(event: MetricEvent): Promise ``` Traite les signaux de métriques pour l'export Cloud. Chaque `MetricEvent` transmis à ce gestionnaire est placé en mémoire tampon et exporté vers le point de terminaison des métriques Cloud dérivé du point de terminaison de base configuré. Aucun filtrage supplémentaire selon le sous-type ou l'état de la métrique n'est effectué dans `CloudExporter`. L'exporter transmet chaque événement de métrique reçu, sauf s'il est désactivé. **Renvoie :** `Promise` après acceptation de l'événement de métrique pour sa mise en mémoire tampon. ### `onScoreEvent` ```typescript async onScoreEvent(event: ScoreEvent): Promise ``` Traite les signaux de score pour l'export Cloud. Chaque `ScoreEvent` transmis à ce gestionnaire est placé en mémoire tampon et exporté vers le point de terminaison des scores Cloud dérivé du point de terminaison de base configuré. Aucun filtrage supplémentaire n'est effectué au niveau de l'exporter, hormis la vérification de sa désactivation ; tous les événements de score reçus par cette méthode sont donc transmis. **Renvoie :** `Promise` après acceptation de l'événement de score pour sa mise en mémoire tampon. ### `onFeedbackEvent` ```typescript async onFeedbackEvent(event: FeedbackEvent): Promise ``` Traite les signaux de retour pour l'export Cloud. Chaque `FeedbackEvent` transmis à ce gestionnaire est placé en mémoire tampon et exporté vers le point de terminaison des retours Cloud dérivé du point de terminaison de base configuré. Aucun filtrage selon le type de retour n'est effectué dans `CloudExporter`. Tous les événements de retour reçus ici sont transmis, sauf si l'exporter est désactivé. **Renvoie :** `Promise` après acceptation de l'événement de retour pour sa mise en mémoire tampon. ### flush ```typescript async flush(): Promise ``` Force l'envoi de tous les événements en mémoire tampon vers la plateforme Mastra sans arrêter l'exporter. 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 ``` Envoie les événements restants et effectue le nettoyage. ## Comportement ### Authentification Si aucun token d'accès n'est fourni dans la configuration ou une variable d'environnement, l'exporter : - Consigne un avertissement avec des informations d'inscription - N'effectue aucune opération (ignore tous les événements) ### Traitement par lots L'exporter regroupe les spans de traçage, logs, métriques, scores et retours afin d'optimiser l'utilisation du réseau : - Effectue un flush lorsque le nombre total d'événements en mémoire tampon atteint `maxBatchSize` - Effectue un flush lorsque `maxBatchWaitMs` s'est écoulé depuis le premier signal placé en mémoire tampon dans le lot - Effectue un flush lors de l'appel à `shutdown()` ### Gestion des erreurs - Utilise des nouvelles tentatives avec backoff exponentiel, dans la limite de `maxRetries` tentatives - Abandonne les lots après l'échec de toutes les tentatives - Consigne les erreurs, mais continue de traiter les nouveaux événements ### 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 de publication complètes explicites sont utilisées telles quelles, même si `projectId` est configuré ### Traitement des signaux - `exportTracingEvent()` exporte uniquement les événements de traçage `SPAN_ENDED` - `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()` et `onFeedbackEvent()` placent en mémoire tampon chaque événement reçu pour leur type de signal respectif - Tous les lots de signaux pris en charge sont envoyés vers leurs points de terminaison de publication Cloud correspondants pendant `flush()` et `shutdown()` ## `MastraCloudSpanRecord` Format interne des spans Cloud : ```typescript interface MastraCloudSpanRecord { traceId: string spanId: string parentSpanId: string | null name: string spanType: string attributes: Record | null metadata: Record | null startedAt: Date endedAt: Date | null input: any output: any error: any isEvent: boolean createdAt: Date updatedAt: Date | null } ``` ## Utilisation ```typescript import { CloudExporter } from '@mastra/observability' // Uses environment variable for token const exporter = new CloudExporter() // Explicit configuration const customExporter = new CloudExporter({ accessToken: 'your-token', projectId: 'project_123', maxBatchSize: 500, maxBatchWaitMs: 2000, logLevel: 'debug', }) ``` ## Voir aussi ### Documentation - [Présentation du traçage](https://mastra.zisheng.pro/fr/docs/observability/tracing/overview) : guide complet - [Exporters](https://mastra.zisheng.pro/fr/docs/observability/integrations/overview) : concepts relatifs aux Exporters ### Autres Exporters - [DefaultExporter](https://mastra.zisheng.pro/fr/reference/observability/tracing/exporters/default-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