Diagnostiquer la santé du SDK

Quand un utilisateur pose des questions sur les versions du SDK PostHog, les SDKs obsolètes, ou s'il devrait mettre à jour, utilise le rapport SDK Doctor pré-traité plutôt que de raisonner sur les versions toi-même. Le backend applique des règles smart-semver (périodes de grâce, seuils de comptage mineur, détection basée sur l'âge), des seuils de pourcentage de trafic, et fournit un texte destiné aux utilisateurs qui correspond exactement à l'interface SDK Doctor.

Outils disponibles

Flux de travail

Étape 1 — Invoquer l'outil

posthog:sdk-doctor-get
{}

Passe force_refresh: true uniquement quand l'utilisateur demande explicitement des données fraîches — par défaut, le rapport utilise un cache Redis rafraîchi toutes les 12 heures.

Étape 2 — Lire le résumé de haut niveau

{
  "overall_health": "healthy" | "needs_attention",
  "health": "success" | "warning" | "danger",
  "needs_updating_count": 0,
  "team_sdk_count": 0,
  "sdks": [ /* évaluations par SDK */ ]
}

Commence par le titre :

• overall_health: healthy — tout est à jour ; dis-le et arrête-toi.
• health: warning — certains SDKs obsolètes mais moins de la moitié des SDKs du projet. Signale comme recommandations de mise à jour.
• health: danger — la majorité des SDKs de l'équipe sont obsolètes. Traite comme urgent.

Étape 3 — Surface le(s) texte(s) de bannière mot pour mot

Le tableau banners de chaque SDK contient zéro ou plusieurs phrases qui correspondent exactement à l'alerte « Time for an update! » du SDK Doctor, par exemple :

La version 7.0.0 du SDK Python a capturé plus de 10 % des événements au cours des 7 derniers jours.

Cite ces phrases mot pour mot. C'est ce que l'utilisateur voit (ou verrait) déjà dans l'interface — reformuler crée une divergence entre le texte de l'agent et celui du produit.

Étape 4 — Rapporter les résultats par SDK

Pour chaque entrée dans sdks, surface :

• readable_name (par ex. Python, Node.js, Web) — utilise ceci dans la prose, pas le lib brut
• latest_version
• severity (none / warning / danger) — utilise ceci pour regrouper ou colorer les résultats

Groupe par gravité (danger en premier, puis warning, puis none). Ignore les SDKs avec needs_updating: false sauf si l'utilisateur a explicitement demandé l'état complet.

Étape 5 — Détail par version (quand l'utilisateur veut des détails)

Le tableau releases de chaque SDK a des lignes par version. Chaque ligne inclut un texte correspondant à l'interface et des liens prêts à l'emploi :

• status_reason — texte du tooltip du badge qui correspond étroitement à l'interface (par ex. "Publié il y a 5 mois. La mise à jour est recommandée.", "Vous avez la dernière version disponible. Cliquez sur 'Releases ↗' ci-dessus pour vérifier.", ou "Publié il y a 2 mois. La mise à jour est une bonne idée, mais ce n'est pas urgent pour l'instant."). Cite directement. Mise en garde : le segment relatif d'âge (« il y a 5 mois », etc.) est calculé avec humanize.naturaltime de Python sur le backend et dayjs().fromNow() dans le navigateur, et les deux bibliothèques ont des seuils différents à certaines limites (par ex. humanize dit "il y a 30 jours" où dayjs dit "il y a un mois" ; humanize dit "il y a 4 mois" à 148 jours où dayjs dit "il y a 5 mois"). Le template global est identique ; la formulation d'âge peut être décalée d'un seuil. Si un utilisateur cite un âge exact de l'interface qui ne correspond pas, ne le « corrige » pas — l'interface affiche la sortie de dayjs et les deux sont cohérents en interne.
• released_ago — âge relatif lisible (par ex. "il y a 5 mois") — même mise en garde humanize-vs-dayjs que ci-dessus.
• is_outdated, is_old, is_current_or_newer — booléens si tu dois faire une branche
• sql_query — déclaration SQL complète pour voir les 50 derniers événements capturés par cette version. Suggère-la comme snippet copier-coller OU passe-la à posthog:execute-sql pour détailler.
• activity_page_url — chemin relatif (commence par /project/<id>/) vers la page Activity > Explore pré-filtrée par cette lib + version. Combine avec l'hôte PostHog de l'utilisateur (par ex. us.posthog.com) pour un lien cliquable.

Étape 6 — Lien vers l'interface

Termine toujours par un lien vers la page SDK Doctor : /project/<project_id>/health/sdk-doctor. L'interface affiche les comptages d'événements par ligne, les timestamps du dernier événement, les notes de version, et les liens de documentation SDK — plus que la réponse de l'outil n'inclut.

Interpréter la gravité

Le backend applique ces règles (tu n'as pas besoin de les vérifier à nouveau) :

• Période de grâce : les versions publiées au cours des 7 derniers jours (14 jours pour web) ne sont jamais signalées, même si elles sont en retard de plusieurs versions majeures.
• Règle version mineure : signale si 3+ versions mineures en retard OU > 180 jours ancienne.
• Règle version majeure : signale toujours si en retard d'une version majeure (en dehors de la période de grâce).
• Règle version patch : jamais signalée — les différences patch sont du bruit.
• Règle d'âge (flag « old » distinct) : SDKs desktop signalés à > 16 semaines anciens, mobile à > 24 semaines anciens (mobile est plus indulgent — les utilisateurs ne mettent pas les apps à jour automatiquement).
• Seuil de trafic : une version obsolète gérant ≥10 % des événements (≥20 % pour web) remonte en alerte de trafic même si une version plus récente est également utilisée. Les SDKs mobile sont exclus des alertes de trafic.
• Gravité globale : danger quand la moitié ou plus des SDKs du projet sont obsolètes, warning quand certains sont obsolètes mais pas la majorité.

Fidélité de copie

Ces champs de réponse sont du texte d'interface utilisateur destiné aux utilisateurs — cite-les mot pour mot, ne reformule pas :

• banners[] — texte d'alerte « Time for an update! » de haut niveau. Correspondance octet par octet avec l'interface.
• releases[].status_reason — texte du tooltip du badge par version. Le template correspond à l'interface, mais la formulation d'âge relatif (« il y a 5 mois », etc.) peut être décalée d'un seuil de limite car le backend utilise humanize et l'interface utilise dayjs. Voir la mise en garde de l'Étape 5.
• readable_name — nom SDK lisible. Correspondance octet par octet avec l'interface.

reason (par SDK) est un résumé programmatique destiné au classement/filtrage, pas à citer aux utilisateurs. Préfère banners[] et status_reason pour la sortie visible par l'utilisateur.

Gérer les champs de détail vides ou en erreur

Si sql_query ou activity_page_url revient comme chaîne vide pour une version particulière, le nettoyeur backend a rejeté lib_version comme potentiellement non sûr à interpoler (par ex. il contenait des caractères de guillemets ou des espaces). Quand cela se produit :

• Surface-le — dis à l'utilisateur « la chaîne de version SDK enregistrée n'a pas l'air sûre à interpoler dans une requête, donc je ne peux pas construire un lien de détail pour elle. » C'est un signal intéressant à noter (cela pourrait indiquer une manipulation de l'instrumentation ou un bug de bibliothèque).
• Ne réessaie PAS — appeler l'outil à nouveau ne changera pas le résultat.
• Ne corrige PAS — ne réécris pas la version ou ne devine pas un substitut sûr et ne le pipe dans posthog:execute-sql. Cela contournerait le nettoyeur.

De la même manière, si tu passes sql_query à posthog:execute-sql et qu'il échoue, surface l'erreur verbatim plutôt que de réécrire la requête. Le template de requête est un miroir verbatim de ce que l'interface SDK Doctor utilise — si la SQL de l'interface ne s'exécuterait pas, quelque chose d'autre ne va pas.

Ne wraps pas, ne tronques pas, ne modifies pas sql_query de quelque manière que ce soit avant de passer à posthog:execute-sql. Pas de SELECT * FROM (<sql_query>) LIMIT 10, pas d'ajout de clauses WHERE, pas de changement de ORDER BY, pas de suppression de colonnes. La requête est le miroir verbatim — si tu as besoin de quelque chose de différent, construis une requête fraîche à partir de zéro avec l'aide de l'utilisateur, ne la dérive pas de sql_query.

Déférer à la documentation pour les questions « pourquoi est-ce toujours obsolète ? »

Quand l'utilisateur exprime une confusion sur une vieille version SDK produisant toujours des événements après qu'il croyait avoir mis à jour — des formulations comme « je pensais avoir mis à jour », « nous avons déjà mis à niveau », « nous avons déployé la nouvelle version mais… », « pourquoi les utilisateurs sont-ils toujours sur l'ancien SDK ? », ou toute variation de « pourquoi ce n'est pas disparu ? » — ne pas improviser une liste de causes. Pointe-les vers la page de documentation canonique plutôt :

https://posthog.com/docs/sdk-doctor/keeping-sdks-current

Cette page est la source de vérité de l'équipe produit sur pourquoi les versions persistent (pinning de snippet HTML, lockfiles dans des apps distinctes, caching CDN ou navigateur, service workers, problèmes de build/déploiement) et quoi faire à ce sujet (chemins de mise à jour auto vs. manuels par SDK). Elle a des diagrammes, un langage spécifique au produit, et restera à jour à mesure que les conseils évoluent — ta version improvisée divergera.

Forme de réponse suggérée :

C'est une question commune avec quelques causes possibles — bundles mis en cache, versions de snippet épinglées, lockfiles dans des apps distinctes, service workers, problèmes de build/déploiement, etc. Plutôt que de deviner ce qui te mord, jette un œil à Keeping SDKs current — cela te guide à travers chaque cause et sa correction. Une fois que tu l'auras parcouru, je peux t'aider à l'affiner pour ta configuration (par ex. en tirant les événements d'activité pour la version obsolète pour voir si c'est une app/domaine/sous-chemin ou réparti partout).

Le déclencheur est l'intention, pas le contenu. Dépasse-toi chaque fois que l'utilisateur exprime la surprise ou la confusion sur la persistance (« toujours », « je pensais avoir mis à jour », « pourquoi les utilisateurs n'ont-ils pas mis à niveau », « pourquoi l'ancien est-il toujours là »), même quand la réponse de l'outil contient techniquement l'âge de la version, la raison, ou la ventilation du trafic. La page de documentation existe parce que les données littérales ne répondent pas au pourquoi, juste au quoi.

Quand NE PAS déférer

Ne pas envoyer l'utilisateur à la page de documentation quand :

• La question concerne un champ spécifique dans la réponse — par ex. « que signifie is_old ? » ou « comment la gravité est-elle calculée ? » — réponds directement en utilisant les champs du rapport ou les règles « Interpréter la gravité » ci-dessous.
• L'utilisateur demande les données brutes (événements, versions en use, comptages, personnes) — tire-les via le rapport ou posthog:execute-sql et présente-les.
• L'utilisateur a déjà lu la page et pose une question de suivi spécifique — réponds directement ou tire des données pour aider à affiner.

Conseils

• Si team_sdk_count vaut 0, le projet n'envoie pas d'événements avec des métadonnées SDK. Suggère de vérifier que posthog-js (ou un autre SDK) est réellement installé et capture des événements.
• Le rapport est par projet. Si l'utilisateur demande plusieurs projets, invoque l'outil une fois par projet (après basculer le contexte du projet via posthog:switch-project).
• L'outil est en lecture seule. Pas d'effets secondaires, pas de limites de taux, sûr d'appeler à tout moment.
• Pour les demandes « montre-moi les événements de cette version obsolète », tu as trois options, ordonnées de la plus à la moins interactive :
  1. Rends un lien cliquable depuis activity_page_url — l'utilisateur explore dans l'interface PostHog.
  2. Passe sql_query à posthog:execute-sql et résume le résultat en ligne.
  3. Cite sql_query comme snippet copier-coller.

Formuler l'offre de détail

Quand tu offres d'ouvrir activity_page_url ou d'exécuter sql_query, décris ce que l'utilisateur verra en termes du SDK étant ancien, pas la page ou la personne. Les données concernent les événements des end-users du client capturés tandis qu'un ancien SDK est chargé — la vieille chose est le SDK, pas la page ou la personne.

• Bon : « Veux-tu que je sorte les événements capturés par cet ancien SDK pour que tu puisses voir quelles pages de ton site le chargent toujours, et quels end-users les frappent ? »
• Bon : « Je peux te montrer quelles URLs du site servent toujours le SDK obsolète et qui génère des événements à partir d'elles. »
• À éviter : « Veux-tu voir quelles pages/personnes sont toujours sur l'ancienne version ? » — les pages n'exécutent pas les versions SDK ; les visiteurs des pages le font. Cette formulation fait penser à l'utilisateur que la vieille chose est la page ou la personne, ce qui est faux.
• À éviter pour web / SDKs serveur : « quels utilisateurs sont sur l'ancien SDK » — les utilisateurs n'installent pas ceux-ci ; l'app/site déployé du client le fait. Pour les SDKs mobile (posthog-ios, posthog-android, posthog-flutter, posthog-react-native), cependant, « les utilisateurs qui n'ont pas mis à jour l'app » EST correct — le SDK est embarqué dans le binaire de l'app et les utilisateurs contrôlent la mise à jour en mettant à jour l'app. La règle s'inverse donc pour mobile : des formulations comme « les end-users exécutant toujours une version d'app plus ancienne » ou « les utilisateurs qui n'ont pas mis à jour vers la dernière version » sont correctes pour les détails mobile.