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

new MastraPlatformExporter(config?: MastraPlatformExporterConfig)

MastraPlatformExporterConfig

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

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

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

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<void> une fois que l’événement de traçage a été accepté pour la mise en mémoire tampon ou ignoré.

onLogEvent

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

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<void> une fois que l’événement de journal a été accepté pour la mise en mémoire tampon.

onMetricEvent

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

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<void> une fois que l’événement de métrique a été accepté pour la mise en mémoire tampon.

onScoreEvent

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

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<void> une fois que l’événement de score a été accepté pour la mise en mémoire tampon.

onFeedbackEvent

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

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<void> une fois que l’événement de retour a été accepté pour la mise en mémoire tampon.

flush

async flush(): Promise<void>

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

async shutdown(): Promise<void>

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 :

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 pour AnyExportedSpan.

Utilisation

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 :

// 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: Guide complet
• Exportateurs: Concepts d’exportateurs

Autres exportateurs

• MastraStorageExporter: 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