> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # 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](https://mastra.zisheng.pro/fr/docs/observability/metrics/overview). ## 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](#troubleshooting). ## 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](https://mastra.zisheng.pro/fr/docs/observability/metrics/overview) - [Interroger les métriques](https://mastra.zisheng.pro/fr/docs/observability/metrics/querying) - [Observability dans Studio](https://mastra.zisheng.pro/fr/docs/studio/observability)