Présentation de l’observabilité

Le système d’observabilité de Mastra vous offre une visibilité sur chaque exécution d’Agent, étape de Workflow, appel de Tool et interaction avec un modèle. Le comportement des Agents dépend des réponses du modèle, des prompts, des Tools, de la mémoire et de l’état des Workflows. L’observabilité vous permet donc d’examiner les décisions prises lors de l’exécution dès le premier jour. Elle capture des signaux complémentaires qui, ensemble, vous aident à comprendre ce que fait votre application et pourquoi.

• Configuration : configurez l’observabilité une seule fois pour les Traces, journaux, métriques et retours.
• Stockage : choisissez les backends de stockage pour conserver les Traces et les journaux, agréger les métriques et interroger les retours.
• Traçage : enregistre chaque opération sous forme de chronologie hiérarchique de spans, en capturant les entrées, les sorties, l’utilisation des tokens et la durée.
• Journalisation : transmet les entrées de journal structurées de votre application et des composants internes de Mastra au stockage d’observabilité, en les corrélant automatiquement aux Traces.
• Métriques : extrait des Traces les données d’utilisation et de coût. Aucune instrumentation supplémentaire n’est nécessaire.
• Retours : stocke les évaluations, commentaires, corrections et autres signaux de révision associés aux Traces et aux spans.
• Intégrations : choisissez des exporters, des ponts et des processeurs de spans pour les processus d’observabilité dans Studio, sur la plateforme hébergée ou auprès de services externes.

Quand utiliser l’observabilité

• Déboguez les comportements inattendus des Agents en examinant l’ensemble du parcours de décision, les appels de Tools et les réponses des modèles.
• Surveillez la latence des Agents, Workflows et Tools afin de repérer les goulots d’étranglement.
• Suivez la consommation de tokens et le coût estimé dans le temps afin de maîtriser les dépenses.
• Diagnostiquez les échecs des Workflows en retraçant l’exécution de chaque étape.
• Comparez les performances des Agents avant et après une modification du prompt ou du modèle.

Articulation des différents composants

Le traçage constitue la base. Lorsque l’observabilité est configurée, chaque exécution d’Agent ou de Workflow, appel de Tool et interaction avec un modèle produit un span. Les spans sont organisés en Traces qui présentent le cycle de vie complet de la requête sous forme de chronologie hiérarchique.

Les métriques sont automatiquement dérivées des Traces. Lorsqu’un span se termine, Mastra extrait sa durée, le nombre de tokens et les estimations de coût sans nécessiter de code supplémentaire. Ces métriques alimentent les tableaux de bord de Studio.

Les journaux sont automatiquement corrélés aux Traces. Chaque appel à logger.info(), logger.warn() ou logger.error() effectué dans un contexte tracé reçoit les identifiants de la Trace et du span actuels. Vous pouvez passer directement d’une entrée de journal à la Trace qui l’a produite.

Les retours enregistrent des signaux de révision humaine tels que des évaluations, des commentaires et des corrections. Ils peuvent être associés aux Traces et aux spans, puis interrogés au moyen du même stockage d’observabilité que les métriques.

Ces signaux partagent des identifiants de corrélation, notamment l’identifiant de Trace, l’identifiant de span, le type et le nom de l’entité. Vous pouvez les utiliser pour passer d’un pic de métrique aux Traces, journaux et retours associés.

Démarrage rapide

Installez @mastra/observability ainsi que des backends de stockage compatibles avec les Traces et les métriques :

npm

npm install @mastra/observability @mastra/libsql @mastra/duckdb

pnpm

pnpm add @mastra/observability @mastra/libsql @mastra/duckdb

Yarn

yarn add @mastra/observability @mastra/libsql @mastra/duckdb

Bun

bun add @mastra/observability @mastra/libsql @mastra/duckdb

Configurez ensuite l’observabilité dans votre instance Mastra. L’exemple suivant utilise le stockage composite pour orienter les données d’observabilité vers DuckDB, qui prend en charge l’agrégation des métriques, tout en conservant le reste dans LibSQL :

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { MastraCompositeStore } from '@mastra/core/storage'
import {
  Observability,
  MastraStorageExporter,
  MastraPlatformExporter,
  SensitiveDataFilter,
} from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: await new DuckDBStore().getStore('observability'),
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [
          new MastraStorageExporter(), // Persists observability events to Mastra Storage
          new MastraPlatformExporter(), // Sends observability events to Mastra platform (if MASTRA_PLATFORM_ACCESS_TOKEN is set)
        ],
        spanOutputProcessors: [
          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
        ],
        logging: {
          enabled: true,
          level: 'info',
        },
      },
    },
  }),
})

Cette configuration active le traçage, la transmission des journaux et les métriques. Mastra prend également en charge des fournisseurs de traçage externes comme Langfuse, Datadog et toute plateforme compatible avec OpenTelemetry. Consultez la section Maintenir l’accès à Studio pour conserver l’accès à Mastra Studio lors de l’envoi de données à un fournisseur externe.

Configuration

L’observabilité se configure une seule fois dans votre instance Mastra et s’applique aux Traces, aux journaux et aux métriques.

Configuration de base

Une configuration d’observabilité contient généralement :

• serviceName : identifiant du service associé aux données d’observabilité exportées.
• exporters : une ou plusieurs destinations pour les Traces, les journaux et les métriques dérivées.
• spanOutputProcessors : transformations exécutées avant l’exportation des spans.
• logging : paramètres de transmission des journaux vers le stockage d’observabilité.

Pour en savoir plus sur les destinations et les processeurs, consultez la présentation des intégrations.

Maintenir l’accès à Studio

Lorsque vous ajoutez des exporters externes, conservez MastraStorageExporter pour l’observabilité dans Studio et/ou MastraPlatformExporter pour l’observabilité hébergée sur la plateforme Mastra.

L’exemple suivant présente uniquement la configuration de l’observabilité. Configurez le stockage séparément.

src/mastra/observability.ts

import { Observability, MastraStorageExporter, MastraPlatformExporter } from '@mastra/observability'
import { ArizeExporter } from '@mastra/arize'

export const observability = new Observability({
  configs: {
    production: {
      serviceName: 'my-service',
      exporters: [
        new ArizeExporter({
          endpoint: process.env.PHOENIX_COLLECTOR_ENDPOINT,
          apiKey: process.env.PHOENIX_API_KEY,
        }),
        new MastraStorageExporter(),
        new MastraPlatformExporter(),
      ],
    },
  },
})

Vider les buffers dans les environnements serverless

Dans les environnements serverless, videz les buffers des exporters d’observabilité avant que l’environnement d’exécution ne soit suspendu ou arrêté :

await mastra.observability.flush()

Dans les environnements serverless, utilisez un stockage externe plutôt qu’un stockage dans un fichier local. Consultez la section Stockage pour choisir et orienter le stockage.

Configuration multiple

Utilisez plusieurs configurations lorsque différents environnements ou types de requêtes nécessitent des exporters ou des stratégies d’échantillonnage distincts. Sélectionnez la configuration active lors de l’exécution avec configSelector.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { Observability, MastraStorageExporter } from '@mastra/observability'
import { LangfuseExporter } from '@mastra/langfuse'

const storageExporter = new MastraStorageExporter()
const langfuseExporter = new LangfuseExporter()

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      development: {
        serviceName: 'my-service-dev',
        exporters: [storageExporter],
      },
      production: {
        serviceName: 'my-service-prod',
        exporters: [storageExporter, langfuseExporter],
      },
    },
    configSelector: () => process.env.NODE_ENV || 'development',
  }),
})

Pour l’échantillonnage des Traces, consultez la section Traçage.

Stockage

Le stockage détermine quels signaux d’observabilité sont conservés, quelles requêtes sont disponibles et si l’agrégation des métriques fonctionne. Utilisez un stockage d’observabilité dédié plutôt que le stockage principal de votre application.

Prise en charge des signaux

La prise en charge du stockage dépend du signal et de la charge de travail. MastraStorageExporter peut conserver les Traces dans ClickHouse, PostgreSQL, MSSQL, MongoDB et LibSQL. Les métriques nécessitent un stockage doté de capacités analytiques :

• DuckDB : recommandé pour les tests et le développement en local.
• ClickHouse : recommandé pour l’observabilité en production à fort volume.
• PostgresStoreVNext : prend en charge les métriques lorsque le domaine d’observabilité est activé. Indiquez toujours une plage temporelle pour éviter d’analyser des partitions entières.
• Plateforme Mastra : utilisez MastraPlatformExporter pour bénéficier d’une observabilité hébergée sans gérer vous-même le backend.

Pour consulter la liste complète des fournisseurs et les stratégies de traçage prises en charge, reportez-vous à l’exporter de stockage Mastra. Utilisez le stockage composite pour orienter séparément le domaine observability lorsque votre stockage principal ne prend pas en charge l’observabilité ou lorsque la charge de travail doit évoluer indépendamment.

Développement local

Pour le développement local, utilisez :

• LibSQLStore pour le stockage principal de l’application
• DuckDBStore pour le domaine observability
• MastraStorageExporter pour accéder à Studio en local

Déploiement en production

Le trafic d’observabilité comporte généralement davantage d’écritures que le reste de l’application. En production :

• Utilisez MastraStorageExporter avec ClickHouse pour le domaine observability lorsque vous conservez les données d’observabilité dans votre propre stockage.
• Utilisez MastraPlatformExporter pour l’observabilité hébergée sur la plateforme Mastra plutôt que de gérer vous-même le backend.
• Utilisez le stockage composite lorsque l’observabilité nécessite un backend ou une stratégie de mise à l’échelle distincts des données principales de votre application.

Pour en savoir plus sur la compatibilité des backends et le comportement de regroupement des exporters, consultez l’exporter de stockage Mastra.

Mastra platform

Pour héberger les Traces, journaux et métriques de plusieurs projets et déploiements, consultez la page Observabilité sur la plateforme Mastra.

Étapes suivantes

• Traçage
• Journalisation
• Métriques
• Retours
• Présentation des intégrations
• Mastra Studio
• Référence des métriques automatiques
• Observabilité sur la plateforme Mastra