Référence des métriques automatiques

Mastra extrait automatiquement des métriques de performances et d’utilisation à partir des exécutions tracées. Cette page constitue la référence complète de tous les noms de métriques, libellés et champs de contexte émis par Mastra.

Pour obtenir les instructions de configuration, consultez la présentation des métriques.

Quand Mastra émet des métriques automatiques

Les métriques sont extraites des spans lorsqu’ils se terminent. La couche d’Observability inspecte chaque span terminé, calcule sa durée et, pour les spans de génération de modèle, lit les données d’utilisation des tokens. Aucune instrumentation manuelle n’est nécessaire.

Facteurs déterminant la disponibilité d’une métrique

Une métrique atteint le stockage lorsque :

1. MastraStorageExporter est configuré comme Exporter.
2. Le backend de stockage prend en charge les métriques (ClickHouse, DuckDB ou Postgres v-next avec le domaine Observability activé).

Si aucune métrique n’est disponible, consultez la section Dépannage.

Métriques de durée

Les métriques de durée enregistrent le temps d’exécution en millisecondes, calculé à partir des horodatages de début et de fin du span. Chaque métrique de durée comprend un libellé status défini sur ok ou error, dérivé de l’état du span.

Nom de la métrique	Type de span	Description
mastra_agent_duration_ms	AGENT_RUN	Durée d’une exécution d’Agent
mastra_tool_duration_ms	TOOL_CALL, MCP_TOOL_CALL, PROVIDER_TOOL_CALL	Durée d’un appel de Tool, y compris les appels de Tools MCP et ceux exécutés par le Provider
mastra_workflow_duration_ms	WORKFLOW_RUN	Durée d’une exécution de Workflow
mastra_model_duration_ms	MODEL_GENERATION	Durée d’une génération de modèle
mastra_processor_duration_ms	PROCESSOR_RUN	Durée d’une exécution de Processor

Métriques d’utilisation des tokens

Les métriques de tokens sont émises uniquement à partir des spans MODEL_GENERATION qui contiennent des données usage. Elles nécessitent les données d’utilisation du Provider.

Métriques des tokens d’entrée

Nom de la métrique	Description
mastra_model_total_input_tokens	Nombre total de tokens d’entrée
mastra_model_input_text_tokens	Tokens de texte dans le prompt d’entrée
mastra_model_input_cache_read_tokens	Tokens lus depuis le cache de prompts (par exemple, Anthropic)
mastra_model_input_cache_write_tokens	Tokens écrits dans le cache de prompts
mastra_model_input_audio_tokens	Tokens audio dans l’entrée (modèles multimodaux)
mastra_model_input_image_tokens	Tokens d’image dans l’entrée (modèles de vision)

Métriques des tokens de sortie

Nom de la métrique	Description
mastra_model_total_output_tokens	Nombre total de tokens de sortie
mastra_model_output_text_tokens	Tokens de texte dans la sortie du modèle
mastra_model_output_reasoning_tokens	Tokens de raisonnement / chaîne de pensée (par exemple, série o d’OpenAI)
mastra_model_output_audio_tokens	Tokens audio dans la sortie du modèle
mastra_model_output_image_tokens	Tokens d’image de sortie

Catégories détaillées de tokens signalées par le Provider

Les métriques de ventilation détaillée, c’est-à-dire toutes sauf total_input et total_output, ne sont émises que lorsque le Provider les signale. Si une catégorie ne contient aucun token, la métrique est ignorée pour ce span. Le niveau de détail signalé varie selon les Providers. Par exemple, tous ne signalent pas les tokens de cache ou audio.

Contexte relatif aux coûts

Quand le contexte de coût est associé

Le contexte de coût est associé aux métriques de tokens lorsque le Provider signale un coût valide pour chaque étape de modèle terminée, ou lorsque le registre tarifaire intégré contient une entrée correspondant au Provider et au modèle. Mastra additionne les coûts par étape du Provider en un total unique pour la requête. Si une étape terminée ne dispose pas d’un coût valide signalé, Mastra utilise le registre tarifaire au lieu de communiquer un total partiel. Si aucune source n’est disponible, les métriques de tokens sont tout de même émises, sans champs de coût.

Un costContext fourni par l’appelant est prioritaire sur les coûts signalés par le Provider et les estimations du registre tarifaire. Les totaux signalés par le Provider utilisent costMetadata.source: 'provider_reported', costMetadata.scope: 'query_total' et costMetadata.reportedStepCount pour identifier la source, la portée et le nombre d’étapes terminées incluses dans le total.

Champs de coût pouvant être inclus

Champ	Description
provider	Nom du Provider (par exemple, openai ou anthropic)
model	Identifiant du modèle (par exemple, gpt-4o ou claude-sonnet-4-20250514)
estimatedCost	Coût estimé à partir du nombre de tokens et du niveau tarifaire, ou total signalé par le Provider
costUnit	Unité monétaire (par exemple, USD)
costMetadata	Contexte tarifaire supplémentaire, comprenant les informations de niveau, les détails des erreurs ainsi que la source et la portée du coût signalé par le Provider

Corrélation avec les traces

Relation entre les métriques, les spans et le contexte de trace

Chaque métrique transporte un instantané CorrelationContext provenant du span qui l’a produite. Ce contexte est stocké avec la valeur de la métrique et relie celle-ci au span et à la trace exacts.

Les champs de corrélation se répartissent dans les catégories suivantes :

Corrélation de trace

• traceId : identifiant de la trace
• spanId : identifiant du span
• tags : tags du span

Hiérarchie des entités

• entityType, entityId, entityName : entité qui a produit la métrique (par exemple, Agent ou Workflow)
• parentEntityType, parentEntityId, parentEntityName : entité parente
• rootEntityType, rootEntityId, rootEntityName : entité racine de la chaîne d’appels

Identité

• userId, organizationId, resourceId : contexte d’identité provenant de la requête
• runId, sessionId, threadId, requestId : ID de corrélation

Déploiement

• environment : environnement de déploiement (par exemple, production ou staging)
• source : identifiant de la source
• serviceName : nom du service provenant de la configuration d’Observability
• experimentId : identifiant de l’expérience, le cas échéant

Utilité de la corrélation pour le débogage

Lorsque vous repérez un pic de latence ou d’utilisation des tokens dans le tableau de bord Metrics, le contexte de corrélation vous permet d’accéder directement à la trace qui a produit la métrique. Vous pouvez ensuite inspecter le span concerné. La cause racine peut être un appel de Tool lent, un prompt volumineux ou encore une erreur inattendue.

Dépannage

Aucune métrique n’est disponible

• Observability est configurée : vérifiez que votre instance Mastra possède une configuration observability avec au moins un Exporter.
• MastraStorageExporter ou MastraPlatformExporter est présent : les autres Exporters (Datadog, Langfuse, etc.) n’affichent pas les métriques dans Mastra. MastraStorageExporter est requis pour le tableau de bord Studio local, et MastraPlatformExporter est requis pour afficher les métriques sur Mastra Platform.
• Le Storage prend en charge les métriques : les métriques nécessitent un stockage adapté à l’analyse (ClickHouse, DuckDB ou Postgres v-next avec le domaine Observability activé). Les autres bases de données orientées lignes (LibSQL, MSSQL) et les bases de données documentaires (MongoDB) ne prennent pas en charge les métriques.
• L’échantillonnage n’est pas de 0 % : si la probabilité d’échantillonnage vaut 0 ou si la stratégie vaut never, tous les spans deviennent des opérations sans effet et aucune métrique n’est extraite.

Les métriques de durée sont absentes

• Le span possède des horodatages : la durée est calculée à partir de startTime et endTime. Si l’un des deux est absent, la métrique est ignorée.
• Le type de span correspond à une métrique : seuls les spans AGENT_RUN, TOOL_CALL, MCP_TOOL_CALL, PROVIDER_TOOL_CALL, WORKFLOW_RUN, MODEL_GENERATION et PROCESSOR_RUN produisent des métriques de durée.

Les métriques de tokens sont absentes

• Le span correspond à une génération de modèle : les métriques de tokens sont uniquement émises à partir des spans MODEL_GENERATION.
• Le Provider signale l’utilisation : le Provider du modèle doit inclure des données usage dans sa réponse. Ces données sont requises pour émettre les métriques de tokens.

Voir aussi

• Présentation des métriques
• Interroger les métriques
• Observability dans Studio