> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# Interroger les métriques

Mastra expose les cinq mêmes requêtes OLAP (`getMetricAggregate`, `getMetricBreakdown`, `getMetricTimeSeries`, `getMetricPercentiles` et les utilitaires de découverte) via trois interfaces : un accesseur de magasin dans le processus, l'API HTTP du runtime et la CLI `mastra api metric`. Toutes trois acceptent les mêmes structures d'entrée validées par Zod. Vous pouvez ainsi passer d'une investigation ponctuelle avec la CLI à un outil de tableau de bord programmatique sans avoir à réapprendre l'API.

**Pour les agents IA :** exécutez `npx mastra api metric aggregate '{"name":"mastra_agent_duration_ms","aggregation":"avg"}'` pour interroger directement la latence moyenne des agents au lieu d'écrire un script temporaire. L'interrogation des métriques locales nécessite un serveur Mastra en cours d'exécution avec un magasin d'observabilité compatible OLAP. Démarrez le serveur local avec `npx mastra dev`, ou transmettez l'URL de base du serveur accessible avec `--url`. Exécutez `npx mastra api metric aggregate --schema` avant de construire une autre requête. Installez la skill Mastra avec `npx skills add mastra-ai/skills --skill mastra` pour bénéficier d'instructions complètes sur la découverte de la CLI de l'API, le ciblage, le schéma, l'authentification et la gestion des erreurs.

## Quand utiliser cette fonctionnalité

- Créer un tableau de bord ou une tuile d'indicateur clé de performance (KPI) personnalisé en complément de Studio.
- Alimenter une alerte planifiée qui se déclenche lorsque le coût des tokens ou la latence dépasse un seuil.
- Fournir à un agent un outil qui lit ses propres métriques de performance et les explique dans une conversation.
- Effectuer des investigations ponctuelles depuis un terminal avec `mastra api metric ...`.

Pour configurer le magasin d'observabilité lui-même, consultez la [présentation des métriques](https://mastra.zisheng.pro/fr/docs/observability/metrics/overview). Pour connaître la liste des noms de métriques que vous pouvez interroger, consultez la [référence des métriques automatiques](https://mastra.zisheng.pro/fr/reference/observability/metrics/automatic-metrics).

> **Remarque:** Les requêtes de métriques sont prises en charge par le domaine d'observabilité, qui nécessite un magasin compatible OLAP (DuckDB en local, ClickHouse en production). Consultez la [présentation des métriques](https://mastra.zisheng.pro/fr/docs/observability/metrics/overview) pour la configuration. Si le magasin d'observabilité n'est pas configuré, `getStore('observability')` renvoie `null`.

## Interfaces

### Dans le processus

Dans un outil, une route de serveur ou une étape de workflow, récupérez le magasin d'observabilité depuis le stockage Mastra :

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const agentLatencyTool = createTool({
  id: 'agentLatency',
  description: 'Average agent latency over the last hour.',
  inputSchema: z.object({}),
  execute: async (_input, context) => {
    const observability = await context.mastra!.getStorage()!.getStore('observability')
    if (!observability) {
      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
    }

    const result = await observability.getMetricAggregate({
      name: ['mastra_agent_duration_ms'],
      aggregation: 'avg',
      filters: {
        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
      },
    })

    return { averageMs: result.value }
  },
})
```

`getStore('observability')` renvoie `null` lorsque le backend configuré ne prend pas en charge les requêtes OLAP.

### HTTP

Le serveur `mastra dev` (comme tout runtime Mastra déployé) expose les mêmes requêtes sous `/api/observability/metrics/*`. Les endpoints d'agrégation, de répartition, de séries temporelles et de percentiles acceptent un corps JSON avec `POST`. Les endpoints de découverte utilisent `GET` avec des paramètres de requête.

```bash
curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
  -H "content-type: application/json" \
  -d '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}'
```

Routes disponibles :

- `POST /api/observability/metrics/aggregate`
- `POST /api/observability/metrics/breakdown`
- `POST /api/observability/metrics/timeseries`
- `POST /api/observability/metrics/percentiles`
- `GET /api/observability/metrics` (lignes brutes, paginées)
- `GET /api/observability/discovery/metric-names`
- `GET /api/observability/discovery/metric-label-keys`
- `GET /api/observability/discovery/metric-label-values`

Le SDK `@mastra/client-js` encapsule ces mêmes routes avec `mastraClient.getMetricAggregate(...)`, `getMetricBreakdown(...)`, etc.

### CLI

`mastra api metric ...` appelle les mêmes endpoints avec un seul argument JSON, ce qui permet à un agent ou à un script shell de récupérer des métriques sans écrire de code :

```bash
mastra api metric aggregate \
  '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}' \
  --url http://localhost:4111
```

Par défaut, la CLI cible l'observabilité Mastra hébergée (`https://observability.mastra.ai`). Transmettez `--url http://localhost:4111` pour interroger un serveur `mastra dev` local. Consultez [`mastra api metric aggregate`](https://mastra.zisheng.pro/fr/reference/cli/mastra) et les entrées voisines pour obtenir la liste complète des commandes.

## Requêtes

### `getMetricAggregate`

Renvoie une valeur scalaire unique, qui constitue la brique de base des cartes de KPI.

Entrées :

- `name` : tableau contenant un ou plusieurs noms de métriques.
- `aggregation` : l'une des valeurs `'sum' | 'avg' | 'min' | 'max' | 'count' | 'count_distinct' | 'last'`.
- `filters` : [objet de filtrage](#filtering) facultatif.
- `comparePeriod` : valeur facultative parmi `'previous_period' | 'previous_day' | 'previous_week'` pour effectuer une comparaison d'une période à l'autre.

Réponse :

- `value`, `previousValue`, `changePercent`.
- `estimatedCost`, `costUnit`, `previousEstimatedCost`, `costChangePercent` pour les métriques de tokens.

```typescript
const observability = await mastra.getStorage()!.getStore('observability')

const cost = await observability!.getMetricAggregate({
  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
  aggregation: 'sum',
  comparePeriod: 'previous_day',
})

console.log(cost.value, cost.estimatedCost, cost.costUnit, cost.changePercent)
```

### `getMetricBreakdown`

Regroupe les lignes selon une ou plusieurs dimensions et agrège chaque groupe. Il s'agit de la brique de base des tableaux des N premiers résultats (par exemple, « tokens par agent »).

Entrées :

- `name` : tableau de noms de métriques.
- `groupBy` : tableau de champs utilisés pour le regroupement (par exemple `['entityName']`).
- `aggregation` : même énumération que ci-dessus.
- `limit` : limite des K premiers résultats côté serveur. Obligatoire pour une propriété `groupBy` à forte cardinalité.
- `orderDirection` : `'ASC' | 'DESC'` (valeur par défaut : `DESC`).
- `filters` : facultatif.

Réponse : `groups[]`, dont chaque élément contient `dimensions` (un enregistrement associant les clés de groupe à leurs valeurs), `value` et `estimatedCost`.

```typescript
const byAgent = await observability!.getMetricBreakdown({
  name: ['mastra_model_total_input_tokens'],
  groupBy: ['entityName'],
  aggregation: 'sum',
  limit: 10,
  orderDirection: 'DESC',
})
```

### `getMetricTimeSeries`

Regroupe les valeurs dans des intervalles fixes, ce qui constitue la brique de base des graphiques en courbes et en barres.

Entrées :

- `name` : tableau de noms de métriques.
- `interval` : l'une des valeurs `'1m' | '5m' | '15m' | '1h' | '1d'`.
- `aggregation` : même énumération.
- `groupBy` : facultatif. Lorsqu'il est omis, les valeurs de plusieurs métriques sont additionnées dans une seule série. Effectuez un appel par métrique pour les conserver séparément.
- `filters` : facultatif.

Réponse : `series[]`, dont chaque élément contient `name`, `costUnit` et un tableau `points[]` d'objets `{ timestamp, value, estimatedCost }`.

```typescript
const inputTokens = await observability!.getMetricTimeSeries({
  name: ['mastra_model_total_input_tokens'],
  aggregation: 'sum',
  interval: '1h',
  filters: {
    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
  },
})
```

### `getMetricPercentiles`

Renvoie les valeurs des percentiles regroupées par intervalle de temps, ce qui constitue la brique de base des graphiques de latence.

Entrées :

- `name` : nom d'une seule métrique (une chaîne, pas un tableau).
- `percentiles` : tableau de nombres compris entre `0` et `1`, par exemple `[0.5, 0.95, 0.99]`.
- `interval` : même énumération que `getMetricTimeSeries`.
- `filters` : facultatif.

Réponse : `series[]`, dont chaque élément contient `percentile` et un tableau `points[]` d'objets `{ timestamp, value }`.

```typescript
const latency = await observability!.getMetricPercentiles({
  name: 'mastra_agent_duration_ms',
  percentiles: [0.5, 0.95],
  interval: '1h',
})
```

### Découverte

Utilisez ces endpoints pour alimenter des listes déroulantes ou pour fournir à un agent le menu des valeurs qu'il peut utiliser pour filtrer. Toutes les routes de découverte utilisent `GET` et se trouvent sous `/api/observability/discovery/`.

**Propres aux métriques** (également exposées comme sous-commandes de `mastra api metric`) :

| Méthode                | Arguments                                   | Suffixe du chemin     | CLI                              |
| ---------------------- | ------------------------------------------- | --------------------- | -------------------------------- |
| `getMetricNames`       | `{ prefix?, limit? }`                       | `metric-names`        | `mastra api metric names`        |
| `getMetricLabelKeys`   | `{ metricName }`                            | `metric-label-keys`   | `mastra api metric label-keys`   |
| `getMetricLabelValues` | `{ metricName, labelKey, prefix?, limit? }` | `metric-label-values` | `mastra api metric label-values` |

**Partagées avec les traces et les journaux** (HTTP uniquement, sans sous-commande CLI dédiée) :

| Méthode           | Arguments         | Suffixe du chemin |
| ----------------- | ----------------- | ----------------- |
| `getEntityTypes`  | `{}`              | `entity-types`    |
| `getEntityNames`  | `{ entityType? }` | `entity-names`    |
| `getServiceNames` | `{}`              | `service-names`   |
| `getEnvironments` | `{}`              | `environments`    |
| `getTags`         | `{ entityType? }` | `tags`            |

## Filtrage

Toutes les requêtes acceptent le même objet `filters`. Les champs les plus utiles sont les suivants :

- `name` : limite la recherche à des noms de métriques précis. (La propriété `name` de premier niveau remplit déjà cette fonction pour les agrégations, les répartitions et les séries temporelles. Utilisez `filters.name` pour combiner plusieurs métriques dans une même requête.)
- `timestamp` : `{ start, end, startExclusive, endExclusive }`. Les deux bornes sont facultatives. Omettez `end` pour inclure les données « jusqu'à maintenant ».
- `provider`, `model`, `costUnit` : pour les métriques de tokens et de coût.
- `labels` : correspondance clé-valeur exacte avec les labels des métriques, par exemple `{ status: 'error' }` pour les métriques de durée.
- Champs de corrélation : `entityType`, `entityName`, `parentEntityName`, `rootEntityName`, `userId`, `organizationId`, `resourceId`, `runId`, `sessionId`, `threadId`, `requestId`, `executionSource`, `environment`, `serviceName`, `experimentId`, `tags`.

La même structure `filters` fonctionne avec les trois interfaces :

```typescript
// In-process
await observability!.getMetricAggregate({
  name: ['mastra_tool_duration_ms'],
  aggregation: 'avg',
  filters: { entityName: 'weatherTool', labels: { status: 'error' } },
})
```

```bash
# CLI
mastra api metric aggregate \
  '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}' \
  --url http://localhost:4111
```

```bash
# HTTP
curl -sS -X POST http://localhost:4111/api/observability/metrics/aggregate \
  -H "content-type: application/json" \
  -d '{"name":["mastra_tool_duration_ms"],"aggregation":"avg","filters":{"entityName":"weatherTool","labels":{"status":"error"}}}'
```

### Toujours fournir une plage temporelle

`filters.timestamp` est facultatif, mais vous devriez le considérer comme obligatoire pour toute requête exécutée sur un magasin de production. Les tables d'observabilité sont généralement partitionnées (ou découpées en chunks avec TimescaleDB) selon l'heure de l'événement. Lorsque vous fournissez `timestamp.start` (et, idéalement, `end`), le backend peut limiter le traitement aux partitions qui chevauchent la plage, généralement une ou deux. Sans plage temporelle, le planificateur doit analyser toutes les partitions, soit potentiellement des centaines de segments sur une année de rétention. C'est la cause la plus fréquente de lenteur des requêtes OLAP sur les magasins basés sur Postgres.

Une valeur par défaut sûre pour les requêtes ponctuelles consiste à utiliser les dernières 24 heures. Les alertes et les tableaux de bord doivent correspondre à leur fenêtre d'évaluation réelle :

```typescript
await observability!.getMetricAggregate({
  name: ['mastra_agent_duration_ms'],
  aggregation: 'p95',
  filters: {
    timestamp: { start: new Date(Date.now() - 24 * 60 * 60 * 1000) },
  },
})
```

Cette recommandation s'applique à tous les backends (ClickHouse, Postgres v-next et DuckDB), mais elle est particulièrement importante pour Postgres v-next, où chaque borne temporelle manquante entraîne directement l'analyse d'une partition supplémentaire.

## Exemple : créer une tuile de KPI personnalisée

L'outil suivant renvoie le volume de tokens d'entrée et le coût estimé pour la dernière heure. Un agent ou un tableau de bord peut l'appeler comme `structuredContent` sans réimplémenter la requête.

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const tokenKpiTool = createTool({
  id: 'tokenKpi',
  description: 'Returns input-token volume and estimated cost for the last hour.',
  inputSchema: z.object({}),
  outputSchema: z.object({
    inputTokens: z.number().nullable(),
    estimatedCost: z.number().nullable(),
    costUnit: z.string().nullable(),
    changePercent: z.number().nullable(),
  }),
  execute: async (_input, context) => {
    const observability = await context.mastra!.getStorage()!.getStore('observability')
    if (!observability) {
      throw new Error('Observability domain is not configured (requires DuckDB or ClickHouse)')
    }

    const result = await observability.getMetricAggregate({
      name: ['mastra_model_total_input_tokens'],
      aggregation: 'sum',
      filters: {
        timestamp: { start: new Date(Date.now() - 60 * 60 * 1000) },
      },
      comparePeriod: 'previous_period',
    })

    return {
      inputTokens: result.value,
      estimatedCost: result.estimatedCost ?? null,
      costUnit: result.costUnit ?? null,
      changePercent: result.changePercent ?? null,
    }
  },
})
```

## Ressources associées

- [Présentation des métriques](https://mastra.zisheng.pro/fr/docs/observability/metrics/overview)
- [Référence des métriques automatiques](https://mastra.zisheng.pro/fr/reference/observability/metrics/automatic-metrics)
- [CLI: `mastra api metric ...`](https://mastra.zisheng.pro/fr/reference/cli/mastra)
- [Observabilité dans Studio](https://mastra.zisheng.pro/fr/docs/studio/observability)