Ajouter la capture de métriques PostHog

Utilisez cette skill pour ajouter la capture de métriques PostHog (compteurs, jauges et histogrammes) pour du code nouveau ou modifié. Utilisez-la après l'implémentation de fonctionnalités ou la révision de pull requests pour assurer que les opérations clés sont mesurées, quand l'utilisateur demande d'ajouter des métriques ou des compteurs, ou pour refléter l'instrumentation de métriques existante dans PostHog. Supporte toute plateforme ou langage.

Plateformes supportées : Web (JavaScript), Node.js, Python via l'API SDK posthog.metrics, Kubernetes via l'agent de métriques, et tout langage via OpenTelemetry (OTLP).

Instructions

Suivez ces étapes DANS L'ORDRE :

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

• Détectez le langage, le framework et la configuration de métriques existante.
• Cherchez les fichiers de dépendances et de projet (package.json, requirements.txt, pyproject.toml, go.mod, pom.xml, etc.).
• Cherchez l'instrumentation de métriques existante : clients Prometheus (prom-client, prometheus_client), clients StatsD/Datadog, compteurs OpenTelemetry, ou une configuration OpenTelemetry Collector.
• Vérifiez si un SDK PostHog (posthog-js, posthog-node, posthog-python) est déjà installé.

ÉTAPE 2 : Choisissez le chemin de capture.

• Si un SDK PostHog est installé (ou si la plateforme en supporte un), utilisez l'API posthog.metrics — aucun package OpenTelemetry nécessaire. Lisez maintenant la référence de plateforme correspondante.
• Si la base de code exporte déjà des métriques OpenTelemetry, pointez l'exportateur OTLP existant (ou Collector) vers PostHog — lisez la référence « Autres langages ». Aucun changement de code applicatif nécessaire au-delà de la configuration de l'exportateur.
• Si aucun des deux ne s'applique, utilisez la référence « Autres langages » comme solution de secours — elle couvre l'approche OpenTelemetry générique.

ÉTAPE 3 : Instrumentez aux côtés des métriques existantes.

• Où la base de code enregistre déjà une métrique (un compteur Prometheus, un appel StatsD, un instrument OTel), ajoutez l'appel PostHog à côté de l'existant, en réutilisant le même nom de métrique et les mêmes attributs. N'ENLEVEZ PAS et ne restructurez PAS l'instrumentation existante.
• N'altérez pas l'architecture fondamentale des fichiers existants. Rendez les ajouts minimes et ciblés.
• Vous devez lire un fichier immédiatement avant de tenter de l'écrire.

ÉTAPE 4 : Ajoutez de nouvelles métriques où elles doivent être.

• Où l'utilisateur a demandé de nouvelles métriques, ou où les opérations clés n'ont pas de couverture, ajoutez des appels de métrique PostHog aux endroits appropriés : comptez les réussites et les échecs des flux critiques, chronométrez les appels externes et les tâches avec des histogrammes, mesurez les profondeurs de file d'attente et les tailles de pool avec des jauges.
• Choisissez le bon type : compteurs pour les choses qui ne font qu'augmenter, jauges pour les valeurs qui augmentent et diminuent, histogrammes pour les distributions comme les durées. Définissez une unité explicite sur les histogrammes (ms, bytes).
• Utilisez des noms stables, descriptifs et séparés par des points (jobs.processed, api.request.duration) et définissez un nom de service pour que les systèmes restent faciles à distinguer.

ÉTAPE 5 : Gardez la cardinalité faible.

• Les attributs comme route, status, plan ou queue sont bons ; les IDs utilisateur, les IDs session, les IDs requête et les timestamps ne le sont pas. Chaque combinaison d'attributs unique crée une nouvelle série.
• Si quelque chose a besoin de détails par utilisateur ou par requête, c'est un travail pour les logs ou traces PostHog, pas pour les métriques.

ÉTAPE 6 : Configurez les variables d'environnement. (Ignorez cette étape si le SDK PostHog est déjà configuré — posthog.metrics réutilise le jeton de projet existant du SDK.)

• Vérifiez si le projet a déjà des variables d'environnement PostHog configurées (par exemple dans .env, .env.local ou des fichiers env spécifiques au framework). Si des valeurs valides existent déjà, ignorez cette étape.
• Si le jeton de projet PostHog manque, utilisez l'outil projects-get du serveur MCP PostHog pour récupérer l'api_token du projet. Si plusieurs projets sont renvoyés, demandez à l'utilisateur quel projet utiliser. Si le serveur MCP n'est pas connecté ou n'est pas authentifié, demandez plutôt le jeton de projet PostHog à l'utilisateur.
• Pour l'URL de l'hôte PostHog : vérifiez la réponse MCP projects-get pour un champ region — US correspond à https://us.i.posthog.com, EU correspond à https://eu.i.posthog.com. Si la région n'est pas disponible à partir de la réponse MCP ou de la configuration de projet existante, demandez à l'utilisateur : « Êtes-vous sur PostHog US Cloud ou EU Cloud ? » N'assumez pas PostHog US Cloud.
• Pour le point de terminaison des métriques OTLP, utilisez https://us.i.posthog.com/i/v1/metrics (US) ou https://eu.i.posthog.com/i/v1/metrics (EU), en correspondance avec la région déterminée ci-dessus, avec le jeton de projet comme en-tête Authorization: Bearer.
• Écrivez ces valeurs dans le fichier 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 7 : Vérifiez que les métriques arrivent.

• Pour les processus de courte durée (scripts, tâches cron, serverless), videz avant la fermeture (posthog.metrics.flush(), ou forceFlush()/shutdown() du fournisseur OTel).
• Ouvrez Métriques dans la barre latérale PostHog et sélectionnez la métrique dans le sélecteur de nom ; les points de données doivent apparaître dans une minute après l'envoi.

Fichiers de référence

• references/javascript.md - Installation des métriques JavaScript (web) - docs
• references/nodejs.md - Installation des métriques Node.js - docs
• references/python.md - Installation des métriques Python - docs
• references/kubernetes.md - Installation des métriques Kubernetes - docs
• references/other.md - Installation des métriques Autres langages - docs
• references/start-here.md - Bien démarrer avec les métriques - docs
• references/basics.md - Pourquoi vous avez besoin de métriques - docs
• references/architecture.md - Comment fonctionnent les métriques - docs
• references/COMMANDMENTS.md - Règles spécifiques au framework que l'intégration doit respecter

Chaque référence de plateforme contient la configuration spécifique du SDK, la configuration OTLP et les patterns d'intégration. Trouvez celui qui correspond à la pile de l'utilisateur.

Principes clés

• Variables d'environnement : Utilisez toujours les variables d'environnement pour les clés PostHog et les points de terminaison OpenTelemetry. Ne les codez jamais en dur.
• Changements minimes : Ajoutez la capture de métriques PostHog aux côtés des métriques existantes. Ne remplacez pas ou ne restructurez pas l'instrumentation existante.
• Préférez le SDK : Quand un SDK PostHog est présent, posthog.metrics n'a besoin d'aucun nouveau package et d'aucune authentification supplémentaire. Réservez la configuration OTLP aux bases de code déjà investies dans OpenTelemetry ou aux langages sans support SDK.
• Cardinalité faible : Chaque combinaison d'attributs unique crée une nouvelle série. Attachez des dimensions bornées comme route, status ou plan — jamais les IDs utilisateur, les IDs session ou les IDs requête.