axiom-metrics-chart

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

L'entrée est une réponse {metadata, series} sauvegardée au format metrics v2 ou v3. Pour les résultats MCP, appelez queryMetrics avec truncate: false et sauvegardez son structuredContent en tant que JSON d'entrée. L'aperçu CSV par défaut peut omettre les séries et les échantillons.

TL;DR

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

# Lire la même réponse sauvegardée depuis stdin :
python3 scripts/metrics_chart.py < response.json

# Forcer un graphique ASCII sans dépendances :
python3 scripts/metrics_chart.py --format ascii response.json

Agrégez d'abord. Les graphiques ne sont lisibles qu'avec une poignée de séries. Le résultat le plus propre provient 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 cette 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 (metrics v2/v3)

{
  "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 les formats v2/v2a (même structure avec un summary par série, ignoré) et la forme bare-array v0/v1, vous pouvez donc alimenter aussi des réponses plus anciennes.

Comportement

• Étiquettes provenant des valeurs de group_keys jointes avec | → 200 | GET (pas code=200,method=GET). Sans group_keys, retombe sur les tags k=v.
• Axe horaire local par défaut ; --tz UTC ou --tz Europe/Berlin pour remplacer.
• 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 (à l'intérieur de --eps, 2 % de la plage y par défaut) ; la plus prominente est conservée.
  2. Top-N par valeur de pic (--top, 8 par défaut).
  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égation dans votre requête.

Formats de sortie

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

• une image en ligne 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 redirigée/capturée (par ex. une enveloppe d'agent IA) et gnuplot est installé — l'agent affiche alors le fichier ;
• ASCII dans un terminal classique, ou quand gnuplot est indisponible.

Forcez un rendu spécifique avec --format :

Si un format d'image est demandé mais gnuplot manque, il affiche une note et retombe sur ASCII — il ne hard-faillle jamais.

Utilisation depuis un agent IA / enveloppe

Les enveloppes de terminal (par ex. pi) réduisent la sortie d'outil et ne repeignent pas l'ANSI en ligne, donc les graphiques ASCII s'affichent en monochrome et repliés. Privilégiez les images : rendez un fichier et laissez l'agent l'afficher. Avec --format auto (le défaut) c'est automatique quand la sortie est redirigée et gnuplot est installé — la 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 devrait alors afficher ce fichier (son outil image/read le rend en ligne, en couleur, déplié). Pour contrôler le chemin, passez --output chart.png. Ne collez pas les octets PNG ou l'ASCII dans le chat.

Options

Dépendances

• Chemin par 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 des graphes nœud-arête ; il n'a pas d'axe numérique/temporel 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é à dessein : c'est une lourde installation pip multi-packages.)

Tests

cd scripts && python3 -m unittest test_metrics_chart -v

Les tests du parser sont épinglés aux golden bytes du service de requête metrics service/query/src/server/tests.rs.