metrics-chart

Convertit une réponse de requête metrics en graphique en courbes multi-séries.

L'entrée est exactement le corps que le service de requête metrics Axiom retourne pour application/vnd.metrics.v3+json — défini dans le service de requête metrics (service/query, JsonV3QueryResponse dans src/server.rs). C'est une série temporelle multi-séries régulièrement échantillonnée ; ce skill la dessine.

TL;DR

# À partir d'un fichier, stdout choisit le meilleur rendu pour votre terminal :
python3 scripts/metrics_chart.py response.json

# À partir d'un pipe (par exemple directement depuis l'API de requête) :
curl ... -H 'Accept: application/vnd.metrics.v3+json' | python3 scripts/metrics_chart.py

# Forcer un graphique ASCII sans dépendances (fonctionne toujours, partout) :
python3 scripts/metrics_chart.py --format ascii response.json

Agréger d'abord. Les graphiques ne sont lisibles qu'avec une poignée de séries. Le meilleur résultat vient d'une requête qui groupe/agrège déjà en quelques lignes (par ex. group by status plutôt que par pod). La réduction de séries de ce skill (ci-dessous) est un filet de sécurité pour les résultats haute cardinalité, pas un substitut à l'agrégation dans la requête.

Format d'entrée (vnd.metrics.v3+json)

{
  "metadata": {
    "group_keys": ["code", "method"],
    "warnings": [],
    "unit": "ms",
    "custom_unit": "millisec"
  },
  "series": [
    {
      "metric": "http_requests",
      "tags": { "code": 200, "method": "GET", "path": "/" },
      "start": 1750753164,
      "resolution": 60,
      "data": [420.0, 42.0, 30.0, 9.0, 15.0, 18.0]
    }
  ]
}

Le parser accepte aussi v2/v2a (même structure avec un summary par série supplémentaire, ignoré) et la forme v0/v1 tableau brut, pour pouvoir traiter les anciennes réponses aussi.

Comportement

• Étiquettes construites à partir des valeurs group_keys jointes avec | → 200 | GET (pas code=200,method=GET). Sans group_keys, se replie sur les tags k=v.
• Axe temps local par défaut ; --tz UTC ou --tz Europe/Berlin pour outrepasser.
• Gaps : les points null cassent la ligne.
• Réduction de séries (sauf --all), dans l'ordre :
  1. Fusionner les séries chevauchantes dont les lignes coïncident essentiellement (dans --eps, défaut 2% de la plage y) ; la plus proéminente est conservée.
  2. Top-N par valeur de pic (--top, défaut 8).
  3. La légende affiche combien ont été supprimées, par ex. showing 8 of 30 series (5 overlapping, 17 low/hidden), plus le conseil d'agréger votre requête.

Formats de sortie

--format auto (défaut) choisit le meilleur rendu pour le contexte :

• une image inline quand gnuplot est installé et le terminal supporte les images (Kitty/Ghostty, iTerm2) ;
• un fichier PNG plus une instruction « afficher ce fichier » quand la sortie est envoyée en pipe/capturée (par ex. par un harness d'agent IA) et gnuplot est installé — l'agent affiche alors le fichier ;
• ASCII dans un terminal classique, ou quand gnuplot n'est pas disponible.

Forcer un backend spécifique avec --format :

Si un format image est demandé mais gnuplot manque, il affiche une note et se replie sur ASCII — il n'échoue jamais.

Utilisation depuis un agent IA / harness

Les harness terminaux (par ex. pi) réduisent la sortie d'outils et ne repeint pas inline ANSI, donc les graphiques ASCII s'affichent en monochrome et repliés. Préférez les images : rendez un fichier et laissez l'agent l'afficher. Avec --format auto (le défaut) c'est automatique quand la sortie est en pipe et gnuplot est installé — le skill écrit un PNG et affiche :

metrics-chart: wrote image to /tmp/metrics-chart-XXXX.png
→ Display this file to the user with your image tool (e.g. read it); do not paste its contents.

L'agent doit alors afficher ce fichier (son outil image/read le rend inline, en couleur, dépilé). Pour contrôler le chemin, passez --output chart.png. Ne collez pas les octets PNG ou l'ASCII en chat.

Options

Dépendances

• Chemin défaut : aucune. Bibliothèque standard Python 3.9+ pure. Le rendu ASCII fonctionne toujours.
• Optionnel : gnuplot (un binaire système) pour PNG/SVG/sixel. Installez seulement si vous voulez des images haute fidélité.

Pourquoi pas graphviz ?

graphviz (dot/neato) dispose les graphes nœud-arête ; il n'a pas d'axe numérique/temps et ne peut pas tracer data[i] dans le temps. Ce payload est une série temporelle numérique sans structure de graphe, donc graphviz ne s'applique pas. gnuplot est le bon backend d'image. (matplotlib est évité volontairement : c'est une lourde installation pip multi-package.)

Tests

cd scripts && python3 -m unittest test_metrics_chart -v

Les tests du parser sont épinglés aux octets d'or du service de requête metrics service/query/src/server/tests.rs.