documentations/kpi_health_check_drilldown_graphs_plan.md

KPI Health Check – Plan final UX Drill-down (Graphes / Groupes KPI / SLA) – V2

Objectifs

• Rendre le drill-down plus lisible pour analyser rapidement un site.
• Permettre une vue “site” où les KPI sont regroupés par nature (success rate, fails, throughput, traffic, availability, etc.).
• Garder une interaction Plotly native: légende cliquable pour masquer/afficher des KPI individuellement.
• Ajouter un benchmark basé sur les SLA/règles (quand c’est pertinent) sans mélanger des KPI hétérogènes.

Non-objectifs (scope control)

• Pas de clustering/ML automatique des KPI.
• Pas de refonte globale de l’UI (on reste dans la section drill-down existante).
• Pas de comparaison multi-sites sur cette itération (site unique, plus lisible).

Contraintes / invariants

• Ne pas casser les fonctionnalités existantes:
  • sélection KPI (kpi_select), comparaison multi-KPI (kpi_compare_select), normalisation, export drill-down.
  • cache des figures et guard anti-récursion déjà en place.
• Les KPI n’ont pas tous la même unité: éviter les graphes qui mélangent des échelles incompatibles.
• Modularité: éviter d’alourdir panel_app/kpi_health_check_panel.py. La logique “métier” de drill-down (groupes, sélection KPI, benchmark, figures) doit être extraite en modules.

Modularité / architecture (production)

Objectif: garder panel_app/kpi_health_check_panel.py comme couche d’orchestration (widgets + callbacks) et déplacer la logique testable dans des modules dédiés.

Découpage proposé:

• process_kpi/kpi_health_check/kpi_groups.py

  • classification KPI -> groupe
  • résolution collisions + règles de priorité
  • sélection top-N (perfs)

• process_kpi/kpi_health_check/benchmarks.py

  • calcul des métriques SLA (median_recent, %BAD recent)
  • calcul quantiles population (si bonus)

• panel_app/kpi_health_check_drilldown_plots.py

  • construction des figures Plotly (trend annoté, timeline BAD)
  • conventions legendgroup + styles

Note: le découpage exact peut être ajusté selon ce qui est le plus simple à tester, mais la contrainte “pas un gros fichier” est un invariant.

Définitions

• KPI “tracé”: KPI qui apparaît comme une trace Plotly (ligne/markers).
• Groupe KPI: catégorie sémantique (success rate / fails / traffic / etc.) utilisée pour filtrer/organiser.
• Benchmark SLA: comparaison au seuil sla des rules, alignée avec la logique is_bad().

1) Groupes KPI “par nature” (meilleure option)

Proposition retenue

• Ajouter un widget: kpi_group_select (Select / Autocomplete / Radio) avec:

  • All (selected KPIs)
  • Success rate (>= SLA / proche 100%)
  • Fails / Drop / Block (<= SLA / proche 0)
  • Throughput / Debit
  • Traffic / Volume
  • Availability / Dispo
  • Latency / Delay
  • Other

• Ajouter un widget: kpi_group_mode (Select):

  • Filter KPI list only (recommended)
  • Add top-N KPIs from group to compare

Comment on conserve la sélection individuelle via Plotly

• Le graphe “Trend (site)” affichera plusieurs traces (1 trace = 1 KPI).
• Les traces seront groupées dans la légende via legendgroup.
• La légende Plotly permet:
  • click: hide/show trace
  • double-click: isolate trace

=> L’utilisateur peut afficher un groupe complet puis isoler un KPI d’un click.

Méthode de classification (règles)

Source of truth + résolution des collisions (production-grade)

• Priorité 1 (future-proof): overrides explicites (si on ajoute plus tard un mapping KPI->groupe dans un fichier/profil).
• Priorité 2: indices issus des rules (direction + présence SLA) quand disponibles.
• Priorité 3: heuristiques sur le nom du KPI (regex).

Règle: un KPI appartient à 0..1 groupe. Si plusieurs regex matchent, on prend le premier match selon l’ordre de priorité défini ci-dessous.

Patterns initiaux (ajustables):

• Success rate: cssr|success|attach|setup|erab|rrc|\basr\b|\bsr\b
• Fails/Drop/Block: drop|fail|block|reject|deny|accessibility.*fail|retention.*fail
• Throughput/debit: throughput|thp|debit|dl.*rate|ul.*rate|bitrate
• Traffic: traffic|volume|erl|payload|gbytes|gb
• Availability: availability|avail|unavailability|unavail|dispo|disponibil|uptime
• Latency: latency|delay|\brt\b|rtt

Note: on évite de matcher sr trop largement (trop de faux positifs). sr est uniquement accepté sous forme de mot (\bsr\b).

1.1) Garde-fous performance (obligatoire en prod)

• Ajouter un paramètre interne max_kpis_in_plot (recommandé: 12).
• Si la liste de KPI à tracer dépasse max_kpis_in_plot:
  • on réduit à top-N selon % BAD days (recent) calculé via is_bad().
  • si égalité, tri secondaire: variance recent ou anomaly_score si disponible.

2) Trend “annoté” (lisibilité)

Ajouts sur le graphe trend

Pour le KPI sélectionné (ou pour chaque KPI tracé quand affichage en groupe):

• Baseline médiane (ligne horizontale)
• Bande de seuil relatif (baseline ± rel_threshold_pct)
• SLA si présent (ligne horizontale)
• Points colorés par jour:
  • OK vs BAD selon is_bad()
• Shading des fenêtres:
  • baseline window
  • recent window

Règle: le status OK/BAD doit être strictement cohérent avec l’engine (utiliser is_bad() et les mêmes paramètres rel_threshold_pct, sla, direction).

Mode groupe

• Si le groupe contient plusieurs KPI:
  • par défaut (recommended): le groupe filtre la liste de KPI proposée à l’utilisateur; le graphe trace kpi_select + kpi_compare_select.
  • option alternative: Add top-N KPIs from group to compare ajoute automatiquement top-N KPI au kpi_compare_select (avec limite max_kpis_in_plot).

3) Timeline “BAD days / streak”

• Ajouter un sous-graphe (subplot) ou un second panneau:
  • une barre par jour: 0/1 BAD
  • annotations: longueur de streak et seuil min_consecutive_days

Objectif: expliquer rapidement le passage DEGRADED -> PERSISTENT.

4) Benchmark basé sur SLA (et option population)

Benchmark SLA (demandé)

• Pour chaque KPI tracé:
  • afficher la ligne SLA si sla est un nombre.
  • afficher une métrique synthèse (annotation ou mini-table):
    • % BAD days (recent) basé sur is_bad().
    • median_recent vs sla.

Cas direction:

• higher_is_better: BAD si (valeur trop basse vs baseline et/ou < SLA selon la règle is_bad).
• lower_is_better: BAD si (valeur trop haute vs baseline et/ou > SLA selon la règle is_bad).

Option “population benchmark” (bonus)

• Afficher p50 et p90 (ou p10/p90 selon direction) sur l’ensemble des sites (ou sur la même City)
• Important:
  • uniquement pour un KPI à la fois (ou normalisation obligatoire)

5) UX / Layout proposé

Dans la section Drill-down:

• Ligne 1: site_select, rat_select
• Ligne 2: kpi_select, kpi_compare_select, kpi_compare_norm
• Ligne 3 (nouveau): kpi_group_select, kpi_group_mode, (option) benchmark_mode
• Plots:
  • Trend annoté (grand)
  • Timeline BAD (petit, dessous)
  • Heatmap / Histogram (déjà existants)

6) Impact code (zones à modifier)

• panel_app/kpi_health_check_panel.py

  • Ajout widgets (group + benchmark options)
  • Orchestration _update_site_view:
    • récupérer les dataframes filtrées
    • appeler les fonctions des modules (group selection / benchmark / plot building)
    • pousser les figures dans les panes
  • Cache: intégrer les nouveaux paramètres dans _drilldown_cache_key.

• process_kpi/kpi_health_check/kpi_groups.py

  • nouvelle logique de groupe KPI + top-N

• process_kpi/kpi_health_check/benchmarks.py

  • nouveaux calculs benchmark SLA (+ population optionnel)

• panel_app/kpi_health_check_drilldown_plots.py

  • builders Plotly (trend annoté + timeline BAD)

Paramètres à ajouter dans la cache key:

• kpi_group_select.value
• kpi_group_mode.value
• benchmark_mode.value
• max_kpis_in_plot

Persistance profil (si on valide):

• kpi_group_selected

• kpi_group_mode

• benchmark_mode

• max_kpis_in_plot (si exposé)

• Optionnel (si on veut isoler la logique):

  • nouveau module utilitaire process_kpi/kpi_health_check/kpi_groups.py (mais on peut rester inline pour v1).

7) Critères d’acceptation

• Quand je sélectionne un site/RAT:
  • je vois un trend lisible avec baseline/seuil/SLA
  • je peux masquer/afficher des KPI dans la légende
• Quand je choisis un groupe:
  • le graphe affiche les KPI du groupe (selon mode)
  • la légende permet d’isoler un KPI
• Le benchmark SLA apparaît seulement si SLA existe.
• Aucun effet de bord sur export / cache / callbacks.

7.1) Risques & mitigations

• Noms KPI hétérogènes (vendors) => fallback Other + regex ajustables.
• Trop de KPI à tracer => max_kpis_in_plot + top-N.
• SLA incohérents (NaN/texte) => ignorer SLA et afficher seulement baseline/seuil.

8) Ordre de livraison (recommandé)

1. Ajouter widgets groupes + logique de sélection KPI (garde-fous perf)
2. Trend annoté (baseline + seuil + SLA)
3. Timeline BAD/streak
4. Population benchmark (optionnel)

Definition of Done (DoD)

• Démo: 1 site 2G + 1 site 3G + 1 site LTE.
• Vérifier que:
  • double-clic tables => drill-down OK.
  • cache drill-down fonctionne (pas de lag, pas de rerender inutile).
  • export drill-down OK.

Questions à valider

• Quels groupes minimum tu veux (liste finale) ?
• En mode groupe, tu veux:
  • tracer tous les KPI du groupe ? ou
  • limiter à ceux cochés dans Compare KPIs ? (recommandé)
• Pour le benchmark:
  • SLA uniquement (demandé)
  • +option population (bonus) ?