Manuel d'utilisation
Trois étapes. Un ZIP. Tout ce dont votre stack Prometheus a besoin pour faire respecter un SLO.
Étape 1 — Service & SLI
Donnez un nom au service que vous voulez mesurer et choisissez le type de SLI qui correspond à la façon dont il expose son état. Ce choix détermine toute la structure PromQL des règles générées.
- Nom du service — Utilisé comme préfixe dans tous les noms de métriques générées. Gardez-le court et compatible slug (ex. api-gateway, checkout, payment-svc).
- Type de SLI — Pilote la formule PromQL. Chaque type calcule le ratio good events / total events différemment — voir la section de référence ci-dessous.
- Méthode de calcul — Request-based compte les événements individuels. Window-based évalue une métrique sur une fenêtre temporelle fixe — requis pour les sondes et les jauges de fraîcheur.
- Métrique Prometheus — La métrique Prometheus sur laquelle ce SLI est construit. Doit correspondre à /^[a-zA-Z_:][a-zA-Z0-9_:]*$/ — pas d'espaces, pas de caractères spéciaux.
- Modèles de démarrage rapide — Cinq cartes de modèles sur la page d'accueil pré-remplissent tous les champs de l'étape 1. Utilisez-les pour éviter la saisie manuelle quand votre service correspond à un profil standard.
- Aperçu PromQL en direct — À mesure que vous tapez le nom de la métrique, l'expression de recording rule se met à jour en direct sous le champ. Inutile d'attendre l'étape 3 pour voir ce que vous générez.
Étape 2 — Objectif & fenêtre
Choisissez votre pourcentage cible, définissez la durée de la fenêtre de mesure, et décidez si le SLO s'applique en permanence ou uniquement pendant les heures ouvrées.
- Objectif (%) — N'importe quelle valeur entre 50 et 99.999 fonctionne. 100 % est rejeté — ça ne laisse aucun error budget, ce qui rend le SLO sans objet.
- Durée de fenêtre — 28–30 jours est le standard. Descendre sous 14 jours rend le calcul du burn rate bruité — les petits pics consomment rapidement le budget.
- Régime horaire — 24/7 mesure tout. Standard, c'est lun–ven 8h–18h. Étendu ajoute le samedi et élargit la plage. Personnalisé vous laisse définir votre propre planning.
- Politiques de burn rate personnalisées — La section Avancé sous le fieldset Horaires métier affiche quatre lignes éditables pré-remplies avec les valeurs Google SRE par défaut. Modifiez-les si votre équipe utilise des cadences d'alerte différentes.
Première fois ? Commencez par 99.9 % sur 28 jours en mode 24/7. Vous pourrez toujours resserrer une fois que vous saurez ce que votre service délivre vraiment.
Étape 3 — Révision & téléchargement
Cet écran montre tout avant que vous validiez : votre SLI, l'objectif, la fenêtre, les quatre paires de politiques de burn rate et le budget d'erreur en minutes. Lisez-le. Si quelque chose semble faux, revenez en arrière.
Cliquez sur « Télécharger le bundle ZIP » et les artefacts se téléchargent immédiatement. Plan Pro ou supérieur requis — chaque téléchargement consomme un crédit. Vérifiez votre profil pour voir combien il vous en reste.
Référence des types de SLI
Le type que vous choisissez détermine tout ce qui concerne la formule PromQL. Ce n'est pas juste une étiquette — ça change le calcul. Voici ce que chaque type signifie.
La fraction des requêtes HTTP ayant retourné un code de succès — 2xx ou 3xx. C'est le SLI par défaut pour les API web, les microservices et tout ce qui est derrière un load balancer.
Métrique exemple
http_requests_total
La fraction des requêtes servies sous votre seuil de latence. Il vous faut une métrique histogram pour ça — le seuil correspond à l'une des valeurs de bucket le.
Métrique exemple
http_request_duration_seconds
La fraction des requêtes qui se sont terminées en erreur, suivie par un label de statut ou de résultat. C'est l'inverse de la disponibilité. Choisissez ce type quand votre service expose des codes d'erreur directement — gRPC en est l'exemple classique.
Métrique exemple
grpc_server_handled_total
Mesure si votre service maintient un volume de traitement au-dessus d'un seuil minimum. La correction et la latence ne sont pas l'enjeu ici — c'est le volume. Consommateurs de file de messages, processeurs de flux, ce genre de chose.
Métrique exemple
kafka_consumer_records_consumed_total
Une métrique de succès 0/1 issue d'une vérification blackbox — HTTP, TCP ou DNS. Elle utilise avg_over_time() pour évaluer la sonde sur une fenêtre fixe plutôt que de compter des requêtes individuelles. Le bon choix pour la surveillance de disponibilité externe.
Métrique exemple
probe_success
La fraction des réponses servies à pleine qualité — pas de fallback dégradé, pas de données partielles, pas de champs manquants. À utiliser quand votre service peut techniquement réussir mais remettre une version appauvrie de ce qui était demandé.
Métrique exemple
api_responses_total
La fraction des sorties qui sont effectivement correctes. Fonctionne mieux pour les jobs batch, les pipelines de données et l'inférence ML — partout où on peut valider le résultat après coup.
Métrique exemple
pipeline_records_processed_total
La fraction des enregistrements que vous attendiez de traiter qui ont effectivement été traités. Pour les pipelines ETL, les crawlers, les jobs d'ingestion — tout workload où il existe un univers connu d'éléments et une deadline pour les traiter.
Métrique exemple
indexer_documents_indexed_total
La fraction des opérations d'écriture confirmées comme durables. Le mode de défaillance ici, c'est la perte de données, pas le downtime. Object stores, bases de données, systèmes de réplication — c'est là que ça s'applique.
Métrique exemple
storage_write_operations_total
La fraction du temps où vos données étaient effectivement fraîches. Elle utilise une jauge binaire — 1 signifie frais, 0 signifie périmé — moyennée sur une fenêtre glissante. Adapté aux pipelines de données, aux caches avec TTL, ou à tout job de reporting où la donnée périmée est le vrai risque.
Métrique exemple
data_freshness_ok
Contenu du bundle ZIP
- prometheus/ recording-rules.yaml + alerting-rules.yaml, tous deux validés par promtool avant packaging.
- alertmanager/ routes.yaml avec les règles de routage, plus les templates de notification page et ticket prêts à intégrer dans Alertmanager.
- grafana/ Deux dashboards Grafana : une vue d'ensemble SLO et un panneau burn rate en temps réel. À importer directement.
- docs/ Runbooks pour les alertes page et ticket, une définition SLO, et une politique error budget — tout en Markdown, prêt à commit.
Déployer votre bundle
Le README.md inclus dans le ZIP contient les instructions complètes pour Kubernetes, Prometheus Operator et le provisioning GitOps. Voici le chemin rapide pour une stack Prometheus bare-metal standard.
-
1. Valider d'abord
Lancez promtool sur les deux fichiers YAML avant de toucher votre serveur. Le bundle inclut des tests unitaires — exécutez-les aussi.
make check && make test -
2. Charger les recording rules
Copiez recording-rules.yaml dans votre répertoire de rules Prometheus et rechargez. Les alerting rules font référence à ces métriques pré-calculées — elles doivent exister avant que les alertes puissent s'évaluer.
cp prometheus/recording-rules.yaml /etc/prometheus/rules/ curl -X POST http://localhost:9090/-/reload -
3. Charger les alerting rules
Copiez alerting-rules.yaml dans le même répertoire et rechargez à nouveau. Quatre politiques multi-burn-rate sont générées : deux de sévérité page et deux de sévérité ticket.
cp prometheus/alerting-rules.yaml /etc/prometheus/rules/ curl -X POST http://localhost:9090/-/reload -
4. Configurer Alertmanager
Copiez les fichiers .tmpl dans votre répertoire de templates Alertmanager. Fusionnez le contenu de routes.yaml dans votre alertmanager.yml sous route.routes — c'est un sous-arbre de routage, pas une config complète.
cp alertmanager/*.tmpl /etc/alertmanager/templates/ amtool check-config /etc/alertmanager/alertmanager.yml curl -X POST http://localhost:9093/-/reload -
5. Importer les dashboards Grafana
Uploadez les deux fichiers .json via Dashboards → Nouveau → Importer dans l'interface Grafana, ou utilisez l'API. Le dossier provisioning/ contient des fichiers de provisioning prêts pour les setups GitOps.
Prometheus nécessite --web.enable-lifecycle pour que l'endpoint de rechargement à chaud fonctionne. Sans cela, un redémarrage complet est nécessaire après avoir copié les rules.
Le README.md dans le ZIP couvre aussi le Prometheus Operator (CRD PrometheusRule), le relabeling business hours avec Grafana Alloy, et la validation CI via le workflow GitHub Actions inclus.