Création de tableaux de bord

Vous concevez des tableaux de bord qui aident les humains à prendre des décisions rapidement. Les tableaux de bord sont des produits : l'audience, les questions et les actions sont plus importantes que le nombre de graphiques.

Philosophie

1. Les décisions d'abord. Chaque panneau répond à une question qui mène à une action.
2. Vue d'ensemble → zoom avant → preuves. Commencez par une vue large, affinez au clic/filtre, terminez par les journaux bruts.
3. Les taux et percentiles plutôt que les moyennes. Les moyennes cachent les problèmes ; p95/p99 les exposent.
4. La simplicité surpasse la densité. Une question par panneau. Pas de décoration inutile.
5. Validez avec les données. Ne devinez jamais les champs—découvrez d'abord le schéma.

Points d'entrée

Choisissez votre point de départ :

Intake : Questions à poser d'abord

Avant de concevoir, clarifiez :

1. Audience et décision

   • Triage oncall ? (rafraîchissement rapide, axé sur les erreurs)
   • Santé de l'équipe ? (tendances quotidiennes, suivi SLO)
   • Rapports exécutifs ? (résumés hebdomadaires, haut niveau)

2. Périmètre

   • Service, environnement, région, cluster, endpoint ?
   • Vue d'un seul service ou multi-services ?

3. Type de dataset (étape obligatoire en premier)

   • Exécutez scripts/metrics/datasets <deploy> pour identifier le kind de chaque dataset
   • Si kind est otel:metrics:v1 → c'est un dataset de métriques. Suivez le chemin Metrics ci-dessous.
   • Sinon → c'est un dataset d'événements/journaux. Suivez le chemin APL ci-dessous.

   ⚠️ N'EXÉCUTEZ JAMAIS getschema sur un dataset de métriques. Les requêtes APL sur les datasets otel:metrics:v1 retournent 0 lignes sans erreur—vous gaspillerez des appels en élargissant les plages de temps avant de réaliser que c'est la mauvaise méthode de découverte.

   Chemin APL (datasets d'événements/journaux) :

   • Découvrez les champs avec getschema :

     ['dataset'] | where _time between (ago(1h) .. now()) | getschema

   • Continuez aux étapes 4–5 ci-dessous.

   Chemin Metrics (datasets otel:metrics:v1) :

   • Exécutez scripts/metrics/metrics-spec <deploy> <dataset> — obligatoire avant de composer une requête MPL
   • Découvrez les métriques disponibles : scripts/metrics/metrics-info <deploy> <dataset> metrics
   • Découvrez les tags : scripts/metrics/metrics-info <deploy> <dataset> tags
   • Explorez les valeurs de tags : scripts/metrics/metrics-info <deploy> <dataset> tags <tag> values
   • Si la découverte retourne des résultats vides, recommencez avec --start défini à 7 jours dans le passé—les métriques éparses (capteurs, jobs batch, crons) peuvent ne pas avoir de données dans la fenêtre par défaut de 24h
   • find-metrics <value> recherche les valeurs de tags, pas les noms de métriques—utilisez-le uniquement quand vous connaissez un nom d'entité spécifique (service, host, device) pour trouver quelles métriques y sont associées
   • Allez directement au Blueprint Metrics/MPL ci-dessous pour la conception des panneaux.

4. Signaux dorés (chemin APL)

   • Trafic : requêtes/sec, événements/min
   • Erreurs : taux d'erreur, nombre 5xx
   • Latence : p50, p95, p99 duration
   • Saturation : CPU, mémoire, profondeur queue, connexions

5. Dimensions de zoom avant (chemin APL)

   • Par quoi les utilisateurs filtrent/groupent-ils ? (service, route, status, pod, customer_id)

Blueprint du tableau de bord

Choisissez le blueprint qui correspond à votre type de dataset (identifié à l'étape 3 d'Intake).

Blueprint APL (datasets d'événements/journaux)

1. Vue d'ensemble (panneaux Statistic)

Des chiffres uniques qui répondent à « est-ce cassé maintenant ? »

• Taux d'erreur (dernières 5m)
• Latence p95 (dernières 5m)
• Taux de requête (dernières 5m)
• Alertes actives (si applicable)

2. Tendances (panneaux TimeSeries)

Des motifs temporels qui répondent à « qu'est-ce qui a changé ? »

• Trafic au fil du temps
• Taux d'erreur au fil du temps
• Percentiles de latence au fil du temps
• Empilés par statut/service pour comparaison

3. Ventilations (panneaux Table/Pie)

Une analyse Top-N qui répond à « où dois-je regarder ? »

• Top 10 routes défaillantes
• Top 10 messages d'erreur
• Pires pods par taux d'erreur
• Distribution des requêtes par statut

4. Preuves (LogStream + SmartFilter)

Des événements bruts qui répondent à « qu'est-ce qui s'est exactement passé ? »

• LogStream filtré aux erreurs
• SmartFilter pour service/env/route
• Champs clés projetés pour la lisibilité

Blueprint Metrics/MPL (datasets de métriques)

Prérequis : Vous DEVEZ avoir exécuté scripts/metrics/metrics-spec et scripts/metrics/metrics-info avant de concevoir les panneaux. Ne devinez jamais la syntaxe MPL ou les noms de métriques/tags.

1. Vue d'ensemble (panneaux Statistic)

Valeurs actuelles des métriques clés—répondez à « quel est l'état en ce moment ? »

• Dernière valeur des métriques principales (p. ex., température actuelle, consommation électrique)
• Utilisez group using avg ou group using last selon le type de métrique (gauge vs counter)

2. Tendances (panneaux TimeSeries)

Tendances des métriques au fil du temps—répondez à « qu'est-ce qui a changé ? »

• Métriques principales au fil du temps, groupées par dimension clé
• Utilisez align to <interval> using avg|sum|last pour une segmentation temporelle correcte
• Groupez uniquement par tags faible cardinalité (≤10 séries par graphique)

3. Ventilations (panneaux TimeSeries ou Table)

Détail par entité—répondez à « où dois-je regarder ? »

• Métriques ventilées par entité (room, host, pod, service)
• Filtrez par valeurs de tags pour garder le nombre de séries gérable
• Utilisez des panneaux séparés par dimension plutôt qu'un graphique surchargé

4. État de l'entité (panneaux TimeSeries ou Table)

Métriques booléennes/état—répondez à « qu'est-ce qui est activé/désactivé/actif ? »

• Utilisez align to <interval> using last pour les métriques d'état
• Les métriques éparses peuvent nécessiter des intervalles d'alignement plus larges (1h+) pour afficher les données

Auto-normalisation de la mise en page

La console utilise react-grid-layout qui nécessite minH, minW, moved et static sur chaque entrée de mise en page. Les scripts dashboard-create et dashboard-update remplissent automatiquement ces champs s'ils sont omis, donc les entrées de mise en page n'ont besoin que de i, x, y, w, h.

Structure de graphique requise

Chaque graphique DOIT avoir un champ id unique. Chaque champ i de l'entrée de mise en page DOIT référencer un id de graphique. Des IDs manquants ou mal appariés corrompront le tableau de bord dans l'interface (état vide, incapacité à sauvegarder/restaurer).

{
  "charts": [
    {
      "id": "error-rate",
      "name": "Error Rate",
      "type": "Statistic",
      "query": { "apl": "..." }
    }
  ],
  "layout": [
    {"i": "error-rate", "x": 0, "y": 0, "w": 3, "h": 2}
  ]
}

Utilisez des IDs en kebab-case descriptifs (p. ex. error-rate, p95-latency, traffic-rps). Les scripts dashboard-validate et deploy l'appliquent automatiquement.

Contrat de graphique Metrics/MPL

Les graphiques sauvegardés par métriques nécessitent à la fois query.apl (la chaîne du pipeline MPL) et query.metricsDataset (le nom du dataset). Le champ metricsDataset est ce qui indique au backend d'interpréter apl comme MPL plutôt que APL—l'omettre cause le dysfonctionnement du graphique même si la chaîne du pipeline est bien formée.

CRITIQUE : Exécutez scripts/metrics/metrics-spec <deployment> <dataset> avant de composer votre première requête MPL dans une session. NE DEVINEZ JAMAIS la syntaxe MPL.

Piège API : Définissez query.metricsDataset au nom du dataset (p. ex. "otel-metrics"). L'API de création rejette query.mpl même si les réponses GET pour les tableaux de bord de métriques existants peuvent l'inclure—mettez la chaîne MPL dans query.apl à la place.

{
  "type": "TimeSeries",
  "query": {
    "apl": "`otel-metrics`:`http.server.duration`\n| where `service.name` == \"api\"\n| align to 1m using avg\n| group by `service.name` using avg",
    "metricsDataset": "otel-metrics"
  }
}

Validez les requêtes avec scripts/metrics/metrics-query avant de les intégrer au JSON du tableau de bord.

Consultez reference/metrics-mpl.md pour le contrat complet et les scripts de découverte.

Types de graphiques

Note : Les requêtes du tableau de bord héritent le temps du sélecteur de l'interface—aucun filtre _time explicite n'est nécessaire.

Validation : TimeSeries, Statistic, Table, Pie, LogStream, Note, MonitorList sont complètement validés par dashboard-validate. Heatmap, ScatterPlot, SmartFilter fonctionnent mais peuvent déclencher des avertissements.

Statistic

Quand : KPI unique, valeur actuelle, comparaison de seuil.

['logs']
| where service == "api"
| summarize 
    total = count(),
    errors = countif(status >= 500)
| extend error_rate = round(100.0 * errors / total, 2)
| project error_rate

Pièges : Ne pas utiliser pour une série temporelle ; vérifiez que la requête retourne une seule ligne.

TimeSeries

Quand : Tendances au fil du temps, comparaison avant/après, changements de taux.

// Métrique unique - utilisez bin_auto pour dimensionnement automatique
['logs']
| summarize ['req/min'] = count() by bin_auto(_time)

// Percentiles de latence - utilisez percentiles_array pour superposition correcte
['logs']
| summarize percentiles_array(duration_ms, 50, 95, 99) by bin_auto(_time)

Bonnes pratiques :

• Utilisez bin_auto(_time) au lieu de bin(_time, 1m) fixe—s'ajuste automatiquement à la fenêtre temporelle
• Utilisez percentiles_array() au lieu de plusieurs appels percentile()—s'affiche comme un graphique
• Trop de séries = illisible ; utilisez top N ou filtrez

Table

Quand : Listes Top-N, ventilations détaillées, données exportables.

['logs']
| where status >= 500
| summarize errors = count() by route, error_message
| top 10 by errors
| project route, error_message, errors

Pièges :

• Utilisez toujours top N pour éviter des résultats illimités
• Utilisez project pour contrôler l'ordre et les noms des colonnes

Pie

Quand : Part du total pour dimensions faible cardinalité (≤6 tranches).

['logs']
| summarize count() by status_class = case(
    status < 300, "2xx",
    status < 400, "3xx",
    status < 500, "4xx",
    "5xx"
  )

Pièges :

• Ne pas utiliser pour haute cardinalité (routes, IDs utilisateur)
• Préférez les tables pour >6 catégories
• Agrégez toujours pour réduire les tranches

LogStream

Quand : Inspection d'événements bruts, débogage, collecte de preuves.

['logs']
| where service == "api" and status >= 500
| project-keep _time, trace_id, route, status, error_message, duration_ms
| take 100

Pièges :

• Incluez toujours take N (100-500 max)
• Utilisez project-keep pour afficher uniquement les champs pertinents
• Filtrez agressivement—les journaux bruts sont coûteux

Heatmap

Quand : Visualisation de distribution, motifs de latence, analyse de densité.

['logs']
| summarize histogram(duration_ms, 15) by bin_auto(_time)

Meilleur pour : Distributions de latence, motifs de temps de réponse, identification de valeurs aberrantes.

Scatter Plot

Quand : Corrélation entre deux métriques, identification de motifs.

['logs']
| summarize avg(duration_ms), avg(resp_size_bytes) by route

Meilleur pour : Corrélation taille de réponse vs latence, motifs d'utilisation des ressources.

SmartFilter (Barre de filtre)

Quand : Filtrage interactif pour l'ensemble du tableau de bord.

SmartFilter est un type de graphique qui crée des filtres dropdown/recherche. Nécessite :

1. Un graphique SmartFilter avec définitions de filtres
2. declare query_parameters dans chaque requête de panneau

Types de filtres :

• selectType: "apl" — Dropdown dynamique à partir de requête APL
• selectType: "list" — Dropdown statique avec options prédéfinies
• type: "search" — Entrée texte libre

Motif de requête de panneau :

declare query_parameters (country_filter:string = "");
['logs'] | where isempty(country_filter) or ['geo.country'] == country_filter

Consultez reference/smartfilter.md pour la structure JSON complète et des exemples de filtres en cascade.

Monitor List

Quand : Afficher l'état du moniteur sur les tableaux de bord opérationnels.

Aucun APL nécessaire—sélectionnez les moniteurs depuis l'interface. Affiche :

• Statut du moniteur (normal/déclenché/arrêt)
• Historique d'exécution (carrés vert/rouge)
• Dataset, type, notifiants

Note

Quand : Contexte, instructions, en-têtes de section.

Utilisez GitHub Flavored Markdown pour :

• Objectif du tableau de bord et audience
• Liens runbook
• Séparateurs de section
• Instructions oncall

Configuration des graphiques

Les graphiques supportent des options de configuration JSON au-delà de la requête. Consultez reference/chart-config.md pour la liste complète.

Référence rapide :

Options communes (tous les graphiques) :

• overrideDashboardTimeRange: boolean
• overrideDashboardCompareAgainst: boolean
• hideHeader: boolean

Motifs APL

Filtrage temporel dans les tableaux de bord vs requêtes ad-hoc

Les requêtes de panneau du tableau de bord n'ont PAS besoin de filtres de temps explicites. Le sélecteur de temps de l'interface du tableau de bord délimite automatiquement toutes les requêtes à la fenêtre temporelle sélectionnée.

// REQUÊTE TABLEAU DE BORD — aucun filtre de temps nécessaire
['logs']
| where service == "api"
| summarize count() by bin_auto(_time)

Les requêtes ad-hoc (onglet Axiom Query, exploration axiom-sre) DOIVENT avoir des filtres de temps explicites :

// REQUÊTE AD-HOC — incluez toujours un filtre de temps
['logs']
| where _time between (ago(1h) .. now())
| where service == "api"
| summarize count() by bin_auto(_time)

Sélection de la taille de bin

Préférez bin_auto(_time)—elle s'ajuste automatiquement à la fenêtre temporelle du tableau de bord.

Tailles de bin manuelles (uniquement quand auto ne convient pas à vos besoins) :

Garde-fous de cardinalité

Prévenez l'explosion de requête :

// BON : borné
| summarize count() by route | top 10 by count_

// MAUVAIS : groupement haute cardinalité non borné
| summarize count() by user_id  // millions de lignes

Échappement de champ

Les champs avec points ont besoin de notation entre crochets :

| where ['kubernetes.pod.name'] == "frontend"

Les champs avec des points DANS le nom (pas la hiérarchie) ont besoin d'échappement :

| where ['kubernetes.labels.app\\.kubernetes\\.io/name'] == "frontend"

Requêtes de signaux dorés

Trafic :

| summarize requests = count() by bin_auto(_time)

Erreurs (en tant que taux %) :

| summarize total = count(), errors = countif(status >= 500) by bin_auto(_time)
| extend error_rate = iff(total > 0, round(100.0 * errors / total, 2), 0.0)
| project _time, error_rate

Latence (utilisez percentiles_array pour la superposition correcte du graphique) :

| summarize percentiles_array(duration_ms, 50, 95, 99) by bin_auto(_time)

Composition de mise en page

Principes de grille

• Largeur du tableau de bord = 12 unités
• Panneau typique : w=3 (quart), w=4 (tiers), w=6 (moitié), w=12 (plein)
• Ligne de stats : 4 panneaux × w=3, h=2
• Ligne TimeSeries : 2 panneaux × w=6, h=4
• Tables : w=6 ou w=12, h=4–6
• LogStream : w=12, h=6–8

Motif de mise en page de section

Row 0-1:  [Stat w=3] [Stat w=3] [Stat w=3] [Stat w=3]
Row 2-5:  [TimeSeries w=6, h=4] [TimeSeries w=6, h=4]
Row 6-9:  [Table w=6, h=4] [Pie w=6, h=4]
Row 10+:  [LogStream w=12, h=6]

Conventions de nommage

• Utilisez des titres en style question : « Error rate by route » plutôt que « Errors »
• Préfixez avec contexte si multi-service : « [API] Error rate »
• Incluez les unités : « Latency (ms) », « Traffic (req/s) »

Paramètres du tableau de bord

Taux de rafraîchissement

Le tableau de bord se rafraîchit automatiquement à l'intervalle configuré. Options : 15s, 30s, 1m, 5m, etc.

⚠️ Avertissement sur le coût des requêtes : Rafraîchissement court (15s) + plage temporelle longue (90d) = requêtes coûteuses s'exécutant constamment.

Recommandations : | Cas d'usage | Taux de rafraîchissement | |------------|----------------------| | Oncall/temps réel | 15s–30s | | Santé équipe | 1m–5m | | Executive/hebdomadaire | 5m–15m |

Partage

Tous les tableaux de bord créés via les tokens API sont partagés avec tout le monde dans l'organisation (owner: "X-AXIOM-EVERYONE"). Les tableaux de bord privés ne sont pas supportés avec les tokens API.

La visibilité des données est toujours régie par les permissions du dataset—les utilisateurs ne voient que les données des datasets auxquels ils peuvent accéder.

Paramètres d'URL de plage temporelle

?t_qr=24h (plage rapide), ?t_ts=...&t_te=... (personnalisée), ?t_against=-1d (comparaison)

Configuration

Exécutez scripts/setup pour vérifier les prérequis (curl, jq, ~/.axiom.toml).

Configuration dans ~/.axiom.toml (partagée avec axiom-sre) :

[deployments.prod]
url = "https://api.axiom.co"
token = "xaat-your-token"
org_id = "your-org-id"

Déploiement

Scripts

⚠️ Deux scripts axiom-api existent avec des comportements différents. scripts/axiom-api réécrit les URLs pour l'API app du tableau de bord (app.*). scripts/metrics/axiom-api utilise les URLs brutes et supporte le routage de déploiement edge. Utiliser le mauvais produira des erreurs 404.

Flux de travail

⚠️ CRITIQUE : Validez toujours les requêtes AVANT de déployer.

Flux de travail APL :

1. Concevoir le tableau de bord (sections + panneaux)
2. Écrire APL pour chaque panneau
3. Créer le JSON (à partir d'un template ou manuellement)
4. Valider les requêtes en utilisant axiom-sre avec filtre de temps explicite
5. dashboard-validate pour vérifier la structure
6. dashboard-create ou dashboard-update pour déployer
7. dashboard-link pour obtenir l'URL—NE CONSTRUISEZ JAMAIS les URLs Axiom manuellement (les IDs org et les URLs de base varient par déploiement)
8. Partager le lien avec l'utilisateur

Flux de travail Metrics/MPL :

1. Exécutez scripts/metrics/metrics-spec pour apprendre la syntaxe MPL
2. Exécutez scripts/metrics/metrics-info pour découvrir les métriques et tags
3. Concevoir le tableau de bord en utilisant le Blueprint Metrics/MPL
4. Écrire MPL pour chaque panneau
5. Valider les requêtes avec scripts/metrics/metrics-query en utilisant une plage temporelle explicite
6. Créer le JSON : mettre la chaîne MPL complète dans query.apl ET définir query.metricsDataset au nom du dataset (obligatoire—indique que le graphique est MPL). Ne définissez pas query.mpl (rejeté par l'API de création).
7. dashboard-validate pour vérifier la structure
8. dashboard-create ou dashboard-update pour déployer
9. dashboard-link pour obtenir l'URL
10. Partager le lien avec l'utilisateur

Intégration de skills frères

spl-to-apl : Traduire Splunk SPL → APL. Mapper timechart → TimeSeries, stats → Statistic/Table. Consultez reference/splunk-migration.md.

axiom-sre : Découvrir le schéma avec getschema, explorer les baselines, identifier les dimensions, puis transformer en panneaux.

query-metrics : Découvrir les datasets de métriques, les noms de métriques, les tags et valeurs de tags. Les scripts de découverte de métriques sont également vendus localement dans scripts/metrics/.

Templates

Templates pré-construits dans reference/templates/ :

Placeholders : {{service}}, {{dataset}}

Utilisation :

scripts/dashboard-from-template service-overview "my-service" "my-dataset" ./dashboard.json
scripts/dashboard-validate ./dashboard.json
scripts/dashboard-create prod ./dashboard.json

⚠️ Les templates supposent des noms de champs (service, status, route, duration_ms). Découvrez d'abord votre schéma et utilisez sed pour corriger les désaccords.

Pièges courants

Référence

• reference/chart-config.md — Toutes les options de configuration des graphiques (JSON)
• reference/metrics-mpl.md — Contrat des graphiques Metrics/MPL et scripts de découverte
• reference/smartfilter.md — Configuration complète de SmartFilter/FilterBar
• reference/chart-cookbook.md — Motifs APL par type de graphique
• reference/layout-recipes.md — Mises en page de grille et blueprints de sections
• reference/splunk-migration.md — Mappage panneau Splunk → Axiom
• reference/design-playbook.md — Principes de conception centrés sur les décisions
• reference/templates/ — Fichiers JSON de tableau de bord prêts à l'emploi

Pour la syntaxe APL : https://axiom.co/docs/apl/introduction