Création d'alertes log

Créer une alerte est un problème de mesure, pas de devinage. Tu n'essaies pas d'être exhaustif — tu essaies de trouver des seuils qui se déclenchent 0–3 fois par semaine sur les vrais patterns de production, sur les services qui comptent.

Quand utiliser cette compétence

• L'utilisateur demande de « configurer des alertes » / « suggérer des alertes » pour son projet.
• L'utilisateur veut évaluer si un service produit un signal d'alerte.
• L'utilisateur vient d'activer les alertes log et veut un ensemble de démarrage.

Quand ne pas utiliser cette compétence

• Affiner une alerte qui existe déjà — c'est un travail différent (utilise posthog:logs-alerts-events-list pour inspecter la cadence de déclenchement/résolution et posthog:logs-alerts-partial-update pour ajuster).
• Enquêter sur un incident en cours — extrais des lignes avec posthog:query-logs, ne crée pas une alerte en plein incident.

Outils

Ne pas appeler posthog:query-logs pendant la création. Tu as besoin de distributions, pas de lignes. Réserve posthog:query-logs à la toute fin si l'utilisateur demande « montre-moi un exemple de ce qui se serait déclenché » — limit: 10 est largement suffisant.

Flux de travail

1. Triage — sélectionner les services candidats

Appelle posthog:logs-services pour les 24h dernières sans filtres. La réponse est plafonnée à 25 services et inclut une sparkline, donc elle est petite et bornée.

Un service est un candidat quand les deux sont vrais :

• log_count est non-trivial (≥ ~1k en 24h — les services plus calmes produisent trop peu de signal pour être alertés).
• error_rate est non-zéro, ou l'utilisateur a nommé le service explicitement.

Saute les services avec haut volume mais error_rate == 0 sauf si l'utilisateur veut une alerte sur la forme du volume (p. ex. « avertis-moi si api-gateway arrête soudainement de produire des logs »). Les alertes volume-plancher utilisent threshold_operator: below et ont besoin d'un raisonnement différent — voir references/volume-floor-alerts.md.

Si l'utilisateur nomme un service, traite-le comme candidat même sans signal d'erreur.

2. (Optionnel) Affiner le filtre

Si un service a de nombreux sous-types d'erreurs, une alerte sur « toutes les erreurs » est généralement trop large. Utilise posthog:logs-attributes-list (essaie attribute_type: log) et posthog:logs-attribute-values-list pour trouver un discriminateur — les courants sont http.status_code, error.type, k8s.container.name. Ajoute le filtre d'affinement à ton brouillon.

Garde-le simple : un filtre de sévérité + un ou deux filtres d'attribut, c'est amplement. Les filtres multi-clauses sont plus difficiles à raisonner et n'améliorent rarement la précision.

3. Baseline — caractériser le candidat sur 7 jours

Appelle posthog:logs-count-ranges avec les filtres du candidat, dateRange: { date_from: "-7d" }, et targetBuckets: 24 (un bucket ≈ 7h). La réponse te donne les counts par bucket.

N'évalue pas les percentiles à vue d'œil ou n'ajuste pas le seuil à la fenêtre d'alerte manuellement. Fais passer la réponse count-ranges dans le script helper :

echo '<count-ranges JSON>' | python3 scripts/baseline_stats.py --window-minutes 5

Le script retourne :

{
  "n_buckets": 12,
  "bucket_minutes": 420.0,
  "alert_window_minutes": 5,
  "stats": { "p50": 12.0, "p95": 71.25, "p99": 126.25, "max": 140 },
  "suggested_threshold_count": 5,
  "rationale": "max(p99=126.25, median*3=36.0, floor=5) scaled from 420m bucket to 5m window",
  "health": []
}

Utilise suggested_threshold_count comme seuil de démarrage. Lis health :

4. Brouillon et simulation

Choisis un brouillon de démarrage parmi ces valeurs par défaut — voir references/threshold-defaults.md pour le raisonnement :

Appelle posthog:logs-alerts-simulate-create avec ces paramètres et date_from: "-7d". La réponse te donne fire_count et resolve_count.

5. Itérer — trois rounds, puis ship ou saute

Cible : fire_count entre 0 et ~3 sur -7d. Si en dehors de la bande :

Quand tu ajustes le seuil, lis les valeurs du bloc stats du script — ne recalcule jamais les percentiles à la main.

Limite l'itération à 3 appels simulate par candidat. Si tu ne peux pas arriver dans la bande en 3 rounds, la métrique est mauvaise — soit le filtre est trop large, soit la fenêtre est mauvaise, soit le service n'a genuinely pas de signal en forme de seuil. Note-le et passe au suivant.

6. Ship — créer + attacher destination

Une fois qu'un brouillon simule proprement :

1. Appelle posthog:logs-alerts-create avec la config validée. Utilise un nom comme <service> error rate (auto) afin que l'utilisateur puisse voir d'un coup d'œil quelles alertes venaient de cette compétence.
2. Appelle posthog:logs-alerts-destinations-create pour la connecter à une cible de notification. Une alerte sans destination est silencieuse. Confirme toujours le nom du canal ou l'URL du webhook avec l'utilisateur avant d'attacher — ne connecte jamais une alerte auto-générée à un canal production sans confirmation explicite. Si l'utilisateur n'est pas sûr, suggère un canal de test à faible trafic pour les premières alertes.

Si l'utilisateur veut des alertes créées en état enabled: false pour review-puis-flip, passe enabled: false à -create et dis-lui combien de brouillons tu as produits.

Forme du filtre — requise

Le champ filters sur posthog:logs-alerts-create prend un sous-ensemble de LogsViewerFilters et doit contenir au moins un de :

• severityLevels — liste de ["trace","debug","info","warn","error","fatal"]
• serviceNames — liste de chaînes de noms de service
• filterGroup — groupe de filtre de propriété

La même forme va dans le champ filters de posthog:logs-alerts-simulate-create. Fais correspondre exactement les filtres de simulation aux filtres d'alerte — sinon la simulation teste une alerte différente de celle que tu ships.

Exemple minimum :

{
  "severityLevels": ["error", "fatal"],
  "serviceNames": ["api-gateway"]
}

Règles d'économie de token

• Un appel posthog:logs-services au démarrage, pas par candidat.
• Un appel posthog:logs-count-ranges par candidat à targetBuckets: 24. Ne dépasse pas 30 pendant la création.
• ≤ 3 appels posthog:logs-alerts-simulate-create par candidat.
• Zéro appel posthog:query-logs pendant la boucle de création.
• Préfère rapporter un petit ensemble d'alertes bien validées à une longue liste de brouillons non validés.

Output

Rapporte ce que tu as fait, dans cette forme :

• Pour chaque alerte shipped : nom, filtres, seuil, fire_count simulé sur 7d, destination.
• Pour chaque candidat sauté : nom du service + pourquoi (baseline flat, ne peut pas arriver au seuil, bas volume).
• Total d'appels simulate faits, total d'alertes créées.

L'utilisateur devrait pouvoir lire cela et décider de désactiver des brouillons avant qu'ils ne deviennent live.