Aller au contenu

Observabilité — SLO & traçage distribué

AKKO embarque d'origine une stack SLO opinionée : métriques Prometheus, dashboards Dashboards, alertes multi-fenêtres multi-burn-rate, et (Sprint 27) traçage distribué via Dashboards Tempo. Cette page explique le concept, les dashboards, et comment ajuster le budget.

Concept — budget d'erreur & burn rate

Un SLO (Service Level Objective) est la cible de fiabilité sur laquelle les utilisateurs comptent, par exemple « ADEN répond correctement à 99 % des requêtes sur 30 jours ». Le budget d'erreur est l'inverse : 1 % des requêtes peuvent échouer sans rompre la promesse.

Un burn rate de 1x signifie que le budget est consommé à la vitesse prévue. 14.4x signifie qu'il est brûlé 14,4 fois plus vite — à ce rythme, le budget mensuel est épuisé en moins de deux jours. AKKO suit le pattern multi-fenêtres multi-burn-rate du Google SRE Workbook :

Fenêtres combinées Burn rate Sévérité Action
1h ET 5m 14.4x warning alerter l'astreinte
6h ET 1h 6x info créer un ticket
1j (records) n/a — dashboard seulement

Les trois dashboards SLO

Les trois sont auto-provisionnés dans Dashboards sous le dossier AKKO SLO grâce au label sidecar grafana_dashboard: "akko".

  1. AKKO — Platform SLO Overview (akko-platform-slo) — disponibilité par tier (ingress, auth, data, IA) + budget restant sur 30 j par tier.
  2. AKKO — ADEN SLO (akko-aden-slo) — latence p50/p95/p99, taux de succès, burn rate multi-fenêtres, requêtes par seconde.
  3. AKKO — Trino AI Plugin (akko-trino-ai-plugin) — latence par fonction (akko_ai_search, ai_gen, akko_ai_embed), taux de hit du cache, état du circuit breaker, requêtes + erreurs.

Ils sont disponibles à https://grafana.<votre-domaine>/dashboards après connexion SSO (Keycloak → Dashboards OIDC).

Traçage distribué — Dashboards Tempo

ADEN est instrumenté OpenTelemetry (FastAPIInstrumentor). Quand AKKO_TRACING_ENABLED=true est positionné sur le pod ADEN, les spans sont exportés en OTLP/gRPC vers le service Tempo interne (akko-tempo:4317). L'API de requête Tempo est branchée comme datasource Dashboards, donc cliquer sur un span dans le dashboard ADEN ouvre la trace correspondante.

Pour activer le traçage sur toute la plateforme, basculer les valeurs :

akko-aden:
  tracing:
    enabled: true
akko-tempo:
  enabled: true     # activé par défaut

Le backend Tempo pointe par défaut sur le système de fichiers local (PVC 10 Gio) — suffisant pour le dev et la petite prod. Pour les déploiements volumineux, basculer vers S3 dans helm/akko/charts/akko-tempo/files/tempo.yaml (commentaire dans le fichier).

Ajuster le budget

Les cibles SLO vivent dans helm/akko/templates/prometheusrule-slo.yaml. Pour durcir la cible ADEN de 99 % → 99,5 %, modifier le facteur de budget dans les expressions aden_query_error_rate_* :

# Avant : > (14.4 * 0.01)   # SLO 99 %  → budget 1 %
# Après : > (14.4 * 0.005)  # SLO 99,5 % → budget 0,5 %

Puis helm upgrade — Prometheus recharge la règle en 30 s.

Alertes livrées

Onze règles d'alerte liées à ADEN et Tempo sont définies :

  • AdenSLOFastBurn — fast-burn (14.4x, fenêtres 1h+5m), warning.
  • AdenSLOSlowBurn — slow-burn (6x, fenêtres 6h+1h), info.
  • AdenTraceIngestionStalled — Tempo n'a reçu aucun span depuis 10 min, warning (pipeline de tracing cassé).

Les recording rules pré-calculent aden_query_success_rate_5m et aden_query_error_rate_{5m,1h,6h,1d} afin que dashboards et alertes partagent les mêmes séries et restent peu coûteux à évaluer.

Où ça tourne

  • Métriques — Prometheus (kube-prometheus-stack), /metrics exposé par ADEN via prometheus-fastapi-instrumentator.
  • Dashboards — sidecar Dashboards, auto-découverts via le label grafana_dashboard: "akko" sur trois ConfigMaps.
  • Alertes — Alertmanager, routées par le pipeline AKKO standard.
  • Traces — Dashboards Tempo (sub-chart akko-tempo), OTLP/gRPC sur 4317, HTTP sur 4318, API de requête sur 3200.