Ajouter le suivi des erreurs avec PostHog

Utilisez cette skill pour ajouter le suivi des erreurs PostHog qui capture et surveille les exceptions dans votre application. Utilisez-la après l'implémentation de fonctionnalités ou l'examen de pull requests pour vous assurer que les erreurs sont suivies avec des stack traces complètes et des source maps. Si PostHog n'est pas encore installé, cette skill couvre également la configuration initiale du SDK. Supporte n'importe quelle plateforme ou langage.

Plateformes supportées : React, Next.js, Web (JavaScript), Node.js, Python, Ruby, Ruby on Rails, Go, Angular, Svelte, Nuxt, React Native, Flutter, Android, et Hono.

Instructions

Suivez ces étapes DANS L'ORDRE :

ÉTAPE 1 : Analysez la base de code et détectez la plateforme.

• Cherchez les fichiers de dépendances (package.json, requirements.txt, go.mod, Gemfile, composer.json, etc.) pour déterminer le langage et le framework.
• Cherchez les fichiers de verrous (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb) pour déterminer le gestionnaire de paquets.
• Vérifiez la présence d'une configuration PostHog existante (initialisation du SDK, variables d'env, etc.). Si PostHog est déjà installé et initialisé, passez à l'ÉTAPE 4.

ÉTAPE 2 : Recherchez l'instrumentation. (À ignorer si PostHog est déjà configuré.) 2.1. Trouvez le fichier de référence ci-dessous qui correspond à la plateforme détectée — c'est la source fiable pour l'initialisation du SDK, la capture automatique d'exceptions et les modèles de suivi des erreurs spécifiques au framework. Lisez-le maintenant. 2.2. Si aucune référence ne correspond, revenez à vos connaissances générales et recherche web. Utilisez posthog.com/docs comme source de recherche principale.

ÉTAPE 3 : Installez et initialisez le SDK PostHog. (À ignorer si PostHog est déjà configuré.)

• Ajoutez le package SDK PostHog pour la plateforme détectée. N'éditez pas manuellement package.json — utilisez la commande d'installation du gestionnaire de paquets.
• Installez toujours les paquets en tant que tâche de fond. N'attendez pas la fin ; passez à d'autres tâches immédiatement après avoir lancé l'installation.
• Suivez la référence du framework pour savoir où et comment initialiser.

ÉTAPE 4 : Activez la capture automatique d'exceptions.

• Suivez la référence de plateforme pour activer la capture automatique d'exceptions. Cela capture automatiquement les exceptions non gérées sans code supplémentaire.

ÉTAPE 5 : Ajoutez les captures d'erreurs manuelles.

• Identifiez les limites d'erreur, les blocs catch et les flux utilisateur critiques où les erreurs doivent être explicitement capturées.
• Ajoutez posthog.captureException() ou l'équivalent de la plateforme à ces endroits.
• N'altérez pas l'architecture fondamentale de la gestion des erreurs existante. Rendez les ajouts minimalistes et ciblés.
• Vous devez lire un fichier immédiatement avant de tenter de l'écrire.

ÉTAPE 6 : Uploadez les source maps (frontend/mobile uniquement).

• Configurez l'upload des source maps pour que les stack traces se résolvent en code source original, non en bundles minifiés.
• Suivez la référence spécifique à la plateforme pour la configuration d'upload (plugins de build, scripts CI, etc.).

ÉTAPE 7 : Configurez les variables d'environnement.

• Vérifiez si le projet possède déjà des variables d'environnement PostHog configurées (par ex. dans .env, .env.local ou des fichiers d'env spécifiques au framework). Si des valeurs valides existent déjà, passez cette étape.
• Si la clé API PostHog est manquante, utilisez l'outil projects-get du serveur MCP PostHog pour récupérer l'api_token du projet. Si plusieurs projets sont retournés, demandez à l'utilisateur quel projet utiliser. Si le serveur MCP n'est pas connecté ou non authentifié, demandez à l'utilisateur sa clé API PostHog à la place.
• Pour l'URL d'hôte PostHog, utilisez https://us.i.posthog.com pour US Cloud ou https://eu.i.posthog.com pour EU Cloud.
• Écrivez ces valeurs dans le fichier d'env approprié en utilisant la convention de nommage du framework.
• Référencez ces variables d'environnement dans le code au lieu de les coder en dur.

ÉTAPE 8 : Vérifiez et nettoyez.

• Vérifiez le projet pour les erreurs. Cherchez les scripts de vérification de type ou de build dans package.json.
• Assurez-vous que les composants créés ont été réellement utilisés.
• Exécutez les scripts linter ou prettier trouvés dans package.json.

Fichiers de référence

• references/react.md - Installation du suivi des erreurs React - docs
• references/web.md - Installation du suivi des erreurs Web - docs
• references/nextjs.md - Installation du suivi des erreurs Next.js - docs
• references/node.md - Installation du suivi des erreurs Node.js - docs
• references/python.md - Installation du suivi des erreurs Python - docs
• references/ruby.md - Installation du suivi des erreurs Ruby - docs
• references/ruby-on-rails.md - Installation du suivi des erreurs Ruby on Rails - docs
• references/go.md - Installation du suivi des erreurs Go - docs
• references/angular.md - Installation du suivi des erreurs Angular - docs
• references/svelte.md - Installation du suivi des erreurs SvelteKit - docs
• references/nuxt.md - Installation du suivi des erreurs Nuxt (v3.7 et supérieur) - docs
• references/react-native.md - Installation du suivi des erreurs React Native - docs
• references/flutter.md - Installation du suivi des erreurs Flutter - docs
• references/android.md - Installation du suivi des erreurs Android - docs
• references/hono.md - Installation du suivi des erreurs Hono - docs
• references/fingerprints.md - Empreintes digitales - docs
• references/alerts.md - Envoyer des alertes de suivi des erreurs - docs
• references/monitoring.md - Surveiller et rechercher des problèmes - docs
• references/assigning-issues.md - Assigner des problèmes aux coéquipiers - docs
• references/upload-source-maps.md - Uploader les source maps - docs

Chaque référence de plateforme contient les modèles d'installation spécifiques au SDK et de capture manuelle. Trouvez celle qui correspond à la stack de l'utilisateur.

Principes clés

• Variables d'environnement : Utilisez toujours les variables d'environnement pour les clés PostHog. Ne les codez jamais en dur.
• Changements minimalistes : Ajoutez le suivi des erreurs aux côtés de la gestion des erreurs existante. Ne remplacez ou ne restructurez pas le code existant.
• Capture automatique d'abord : Activez la capture automatique d'exceptions avant d'ajouter des captures manuelles.
• Source maps : Uploadez les source maps pour que les stack traces se résolvent en code source original, non en bundles minifiés.
• Capture manuelle pour les limites : Utilisez captureException() aux limites d'erreur et dans les blocs catch pour les erreurs qui ne se propagent pas au gestionnaire global.