Vue d’ensemble des métriques

Mastra émet automatiquement des métriques de performances et d’utilisation à partir des exécutions tracées. Aucune instrumentation manuelle n’est nécessaire. Les métriques sont dérivées des spans à mesure qu’ils se terminent.

Les catégories de métriques suivantes sont émises automatiquement :

• Métriques de durée : temps d’exécution des agents, workflows, tools, appels de modèle et processors.
• Métriques d’utilisation de tokens : nombres de tokens d’entrée et de sortie ventilés par type (texte, cache, audio, image, raisonnement).
• Estimation des coûts : coût estimé par appel de modèle, fondé sur un registre de tarifs intégré.

remarque

Les métriques exigent un stockage d’observabilité capable d’analyses. La plupart des bases de données relationnelles, telles que LibSQL et MSSQL, ne prennent pas en charge les métriques. Le stockage en mémoire est réinitialisé au redémarrage.

Pour le développement local, utilisez DuckDB via @mastra/duckdb. Pour la production, utilisez ClickHouse via @mastra/clickhouse. PostgresStoreVNext, avec le domaine Observability activé, prend également en charge les métriques, mais fournissez toujours une plage temporelle afin d’éviter les analyses complètes de partition.

Google Cloud Spanner prend en charge les métriques, mais n’est pas recommandé pour les charges de métriques importantes. L’adaptateur Spanner désactive les métriques par défaut, car elles nécessitent beaucoup d’écritures et d’analyses. Définissez disableMetrics: false uniquement pour les charges légères, ou envoyez les métriques vers un stockage OLAP.

Quand utiliser les métriques

• Surveiller la latence des agents, tools, workflows et appels de modèle
• Suivre la consommation de tokens et les tendances de coûts dans le temps
• Identifier les agents ou tools générant beaucoup d’erreurs en comparant les taux de réussite et d’erreur
• Comparer les performances avant et après des modifications de prompt, de modèle ou de code

Démarrage

Installez les packages requis :

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 Observability avec un stockage composite qui dirige le domaine Observability vers DuckDB :

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, 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()],
        spanOutputProcessors: [new SensitiveDataFilter()],
      },
    },
  }),
})

Studio

Le tableau de bord des métriques de Studio visualise toutes les métriques automatiques avec des cartes KPI, des ventilations détaillées, des chronologies d’utilisation de tokens et des plages temporelles configurables. Consultez Observabilité dans Studio pour une présentation complète.

Ce que mesure Mastra

Mastra émet automatiquement trois catégories de métriques :

• Durée : temps d’exécution en millisecondes des agents, workflows, tools, appels de modèle et processors.
• Utilisation de tokens : nombres de tokens d’entrée et de sortie, ventilés par type (texte, cache, audio, image, raisonnement).
• Estimation des coûts : coût estimé par appel de modèle, fondé sur un registre de tarifs intégré.

Chaque métrique porte le contexte de corrélation de trace ; vous pouvez ainsi passer d’un pic observé dans le tableau de bord au span exact qui l’a provoqué.

Pour la liste complète des noms, libellés et champs de coût des métriques, consultez la référence des métriques automatiques.

Fonctionnement des métriques automatiques

Mastra auto-instrumente les exécutions d’agents, étapes de workflow, appels de tool et générations de modèle sous forme de spans. Lorsqu’un span se termine, la couche Observability en extrait des métriques :

1. Durée : calculée à partir des horodatages de début et de fin du span.
2. Utilisation de tokens : extraite de l’attribut usage des spans de génération de modèle.
3. Estimation des coûts : chaque métrique de token est traitée par un registre de tarifs intégré qui établit la correspondance selon le fournisseur et le nom du modèle.

Avant le stockage, tous les libellés de métrique passent par un filtre de cardinalité qui bloque les valeurs connues à forte cardinalité, telles que les ID de trace et les UUID, afin de préserver l’efficacité du stockage. Les métriques sont ensuite regroupées par un tampon d’événements interne et écrites dans le stockage par MastraStorageExporter.

Étapes suivantes

• Référence des métriques automatiques
• Interroger les métriques
• Présentation du tracing
• Observabilité dans Studio
• Présentation d’Observability
• Référence de MastraStorageExporter