Enquête sur les logs

L'enquête est un problème de rétrécissement : résumez avant de lire. Un appel posthog:logs-patterns compresse des millions de lignes en au maximum 200 templates, et un appel posthog:logs-patterns-diff répond directement à « qu'est-ce qui est différent maintenant par rapport à avant ». Les lignes brutes (posthog:query-logs) sont la dernière étape d'une enquête, jamais la première.

Quand utiliser cette skill

• « Vérifiez les logs » / « le service X est-il en bonne santé ? » / « mon déploiement (ou mise à jour du modèle, changement de config, migration) a-t-il cassé quelque chose ? »
• « Pourquoi les erreurs ont-elles augmenté ? » / « expliquer ce pic » / triage d'incident — « qu'est-ce qui a changé ? »
• « Qu'est-ce que ce service log ? » — orientation dans un flux inconnu ou bruyant.
• Trouver la preuve log d'une défaillance signalée ailleurs (une alerte, un problème de suivi des erreurs, une plainte utilisateur).

Quand ne pas utiliser cette skill

• Créer ou ajuster des alertes log — c'est authoring-log-alerts.
• Analyses sur les événements produit, les personnes ou les insights — c'est querying-posthog-data.
• HogQL expose une table logs via posthog:execute-sql, mais ne pas enquêter via elle : une SQL écrite à la main sur les logs atteint régulièrement les limites de lecture et redérive ce que les outils ci-dessous font en un appel pas cher. Réservez SQL au cas rare où il faut joindre des faits dérivés des logs avec des données non-log.

Outils

La description de chaque outil documente ses paramètres et la forme de sa réponse — lisez-la avant d'appeler.

Choisir le workflow selon la forme de la question

« Est-ce en bonne santé ? » — post-déploiement / vérification post-changement

L'utilisateur a changé quelque chose (déploiement, mise à jour du modèle, config, migration) et veut s'assurer que les logs sont toujours corrects.

1. Pincer le moment du changement et le(s) service(s) affecté(s). Demander si l'utilisateur ne l'a pas dit ; le diff est sans sens sans frontière.
2. S'orienter avec posthog:logs-services-create : le service log-t-il toujours, et quel est son error_rate maintenant ? Un service devenu muet échoue la vérification aussi fortement qu'un qui a commencé à générer des erreurs.
3. posthog:logs-patterns-diff avec query.dateRange du moment du changement à maintenant et baselineDateRange défini sur une fenêtre comparable juste avant le changement, limité à serviceNames. De nouveaux templates error/fatal juste après un changement sont la signature classique de régression ; les décalages de rate_ratio importants sur les templates error existants sont la deuxième chose à vérifier.
4. Vérifier la continuité du volume avec posthog:logs-count-ranges s'étendant avant et après la frontière : une discontinuité de taux (boucle de crash, tempête de redémarrage, silence) apparaît ici même quand le contenu du message semble inchangé.
5. Perforer uniquement les suspects : pivotez chaque template suspect vers les lignes brutes via sa match_regex avec posthog:query-logs.

Un verdict positif exige tous les trois : pas de nouveaux templates error, pas de décalages de rate_ratio error importants, et volume continu. Dites quelles fenêtres vous avez comparées — « en bonne santé » est seulement aussi fort que la baseline.

« Expliquer ce pic »

1. Le localiser : posthog:logs-count-ranges sur la fenêtre de l'utilisateur, puis explorer les buckets denses — chaque date_from/date_to du bucket alimente l'appel suivant. Arrêtez après 3–4 niveaux.
2. L'expliquer : posthog:logs-patterns-diff avec le pic comme query.dateRange et la fenêtre juste avant comme baselineDateRange. Les premières entrées new et rate_shift sont l'explication. Ne minez pas les deux fenêtres séparément et ne faites pas un diff à la main — le diff est un appel.

Triage d'incident — « qu'est-ce qui s'est cassé ? »

posthog:logs-patterns-diff en premier : fenêtre d'incident vs. une fenêtre connue-bonne juste avant (ou omettre la baseline pour même fenêtre-semaine-dernière). Les suspects sont les entrées new et les plus grands décalages rate_ratio ; pivotez chacun vers les lignes brutes. Si le service défaillant est inconnu, le trouver d'abord avec posthog:logs-facet-values-create en facettant service_name sous severityLevels: ["error", "fatal"].

« Que dit ce flux ? » — service inconnu

posthog:logs-patterns sur la dernière heure, limité au service. Scannez les templates par estimated_count et part error non-zéro dans severity_counts. Élargissez la fenêtre ou ajoutez searchTerm seulement si la réponse n'y est pas.

Aiguille connue — un message spécifique, un attribut, ou une personne

Quand la cible est déjà précise (une chaîne d'erreur, un request id, un distinct_id), sauter l'extraction de patterns : découvrir les bonnes clés avec posthog:logs-attributes-list / posthog:logs-attribute-values-list, dimensionner le résultat avec posthog:logs-count, puis tirer les lignes avec posthog:query-logs.

Règles qui gardent les enquêtes honnêtes et pas chères

• Limiter serviceNames (ou un filtre d'attribut de ressource) sur chaque appel une fois le service cible connu. Les appels sans limite scannent tout le flux de l'équipe et affament le budget d'échantillon de patterns.
• posthog:query-logs exige un query.dateRange explicite — l'omettre est un 400, pas une fenêtre par défaut.
• Les comptages de patterns sont des estimations échantillonnées (sampled: true) ; les templates plus rares qu'environ 1 sur 10 000 lignes peuvent être invisibles. L'absence d'un template rare n'est pas la preuve qu'il s'est arrêté.
• Avant de faire confiance à un mur d'entrées new dans un diff, vérifiez baseline.total_count — une baseline minuscule ou vide (logging vient de commencer) fait tout paraître nouveau.
• severityLevels correspond aux six buckets canoniques minuscules contre severity_text exactement. Zéro lignes sur un filtre de sévérité → vérifiez les valeurs stockées avec posthog:logs-attribute-values-list { key: "severity_text" }.
• Budget : un appel services, au maximum un patterns-diff par paire de fenêtres, 3–4 niveaux count-ranges, et query-logs seulement pour les suspects confirmés avec limit ≤ 100.

Sortie

Commencez par le verdict, puis la preuve :

• Verdict : en bonne santé / régressé / inconclusive, avec les fenêtres comparées.
• Suspects (le cas échéant) : template, classification (new / rate_shift), comptages estimés ou rate_ratio, services, et 1–2 exemples de lignes brutes.
• Ce qui a été vérifié et ce qui ne l'a pas été : services couverts, fenêtres, et toute mise en garde sur l'échantillonnage ou la baseline qui limite la confiance.

L'utilisateur devrait pouvoir agir sur le verdict sans relancer l'enquête.

Skills connexes

• authoring-log-alerts — transformer la vérification derrière un verdict en une alerte continue et peu bruyante
• exploring-apm-traces — suivre une ligne de log suspecte dans les traces de requête autour d'elle