CloudExporter

Ajouté dans : @mastra/observability@1.8.0. Obsolète depuis 1.12.0 au profit de MastraPlatformExporter.

Obsolète

CloudExporter est conservé pour assurer la rétrocompatibilité et sera supprimé dans une prochaine version majeure. Utilisez MastraPlatformExporter 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

new CloudExporter(config?: CloudExporterConfig)

CloudExporterConfig

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

readonly name = 'mastra-cloud-observability-exporter';

Méthodes

exportTracingEvent

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

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<void> après acceptation de l'événement de traçage pour sa mise en mémoire tampon ou après son exclusion.

onLogEvent

async onLogEvent(event: LogEvent): Promise<void>

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<void> après acceptation de l'événement de log pour sa mise en mémoire tampon.

onMetricEvent

async onMetricEvent(event: MetricEvent): Promise<void>

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<void> après acceptation de l'événement de métrique pour sa mise en mémoire tampon.

onScoreEvent

async onScoreEvent(event: ScoreEvent): Promise<void>

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<void> après acceptation de l'événement de score pour sa mise en mémoire tampon.

onFeedbackEvent

async onFeedbackEvent(event: FeedbackEvent): Promise<void>

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<void> après acceptation de l'événement de retour pour sa mise en mémoire tampon.

flush

async flush(): Promise<void>

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

async shutdown(): Promise<void>

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 :

interface MastraCloudSpanRecord {
  traceId: string
  spanId: string
  parentSpanId: string | null
  name: string
  spanType: string
  attributes: Record<string, any> | null
  metadata: Record<string, any> | null
  startedAt: Date
  endedAt: Date | null
  input: any
  output: any
  error: any
  isEvent: boolean
  createdAt: Date
  updatedAt: Date | null
}

Utilisation

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 : guide complet
• Exporters : concepts relatifs aux Exporters

Autres Exporters

• DefaultExporter : persistance dans le stockage
• ConsoleExporter : sortie de débogage
• Langfuse : intégration Langfuse
• Braintrust : intégration Braintrust

Référence

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