Ajouter la capture de logs PostHog

Utilisez cette skill pour ajouter la capture de logs PostHog pour du code nouveau ou modifié. Utilisez-la après avoir implémenté des fonctionnalités ou examiné des PRs pour vous assurer que les événements de log significatifs sont capturés avec des propriétés structurées. Si l'export de logs PostHog n'est pas encore configuré, cette skill couvre également la configuration initiale de l'exporteur OTLP. Compatible avec toute plateforme ou langage.

Plateformes supportées : Next.js, Node.js, Python, Go, Java, Datadog, et tout langage via OpenTelemetry.

Instructions

Suivez ces étapes DANS L'ORDRE :

ÉTAPE 1 : Analysez le codebase et détectez la plateforme.

• Détectez le langage, le framework et la configuration de logging existante.
• Recherchez les bibliothèques de log (winston, pino, logging module, logrus, log4j, serilog, etc.).
• Recherchez les fichiers de verrouillage pour déterminer le gestionnaire de paquets.
• Vérifiez s'il existe une configuration d'export de logs PostHog. Si l'exporteur OTLP est déjà configuré, passez à l'ÉTAPE 5 pour ajouter la capture de logs du nouveau code.

ÉTAPE 2 : Recherchez la capture de logs. (Ignorez cette étape si l'export de logs 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 de vérité pour la configuration de l'exporteur OTLP et l'intégration avec la logging existante. Lisez-le maintenant. 2.2. S'il n'existe pas de référence correspondante, utilisez la référence « Other Languages » comme secours — elle couvre l'approche générique OpenTelemetry.

ÉTAPE 3 : Installez les dépendances. (Ignorez cette étape si l'export de logs PostHog est déjà configuré.)

• Installez les paquets SDK OpenTelemetry et exporteur OTLP pour la plateforme détectée.
• Ne modifiez pas manuellement les fichiers de dépendances — utilisez la commande d'installation du gestionnaire de paquets.
• Installez toujours les paquets comme une tâche en arrière-plan. Ne pas attendre la fin ; continuez immédiatement avec les autres travaux.

ÉTAPE 4 : Configurez l'exporteur OTLP. (Ignorez cette étape si l'export de logs PostHog est déjà configuré.)

• Les logs PostHog utilisent le protocole OpenTelemetry. Configurez un exporteur OTLP pointant vers le point de terminaison d'ingestion de PostHog.
• Suivez la référence spécifique à la plateforme pour la configuration exacte.

ÉTAPE 5 : Intégrez-vous avec la logging existante.

• Ajoutez l'exporteur de logs PostHog à côté de la logging existante. Ne remplacez pas les gestionnaires ou sorties de logs existants.
• N'altérez pas l'architecture fondamentale des fichiers existants. Rendez les ajouts minimaux et ciblés.
• Vous devez lire un fichier immédiatement avant de tenter de l'écrire.

ÉTAPE 6 : Ajoutez des propriétés structurées.

• Assurez-vous que les logs incluent des propriétés structurées clé-valeur pour le filtrage et la recherche dans PostHog.
• Préférez les formats de logs structurés avec propriétés clé-valeur aux messages en texte brut.

É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 les fichiers env spécifiques au framework). Si des valeurs valides existent déjà, ignorez cette étape.
• Si la clé API PostHog manque, 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 pas authentifié, demandez à l'utilisateur sa clé API de projet 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.
• Pour le point de terminaison OpenTelemetry, utilisez https://us.i.posthog.com/v1 (US) ou https://eu.i.posthog.com/v1 (EU).
• É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.

Fichiers de référence

• references/nextjs.md - Installation des logs Next.js - docs
• references/nodejs.md - Installation des logs Node.js - docs
• references/python.md - Installation des logs Python - docs
• references/go.md - Installation des logs Go - docs
• references/java.md - Installation des logs Java - docs
• references/datadog.md - Installation des logs Datadog - docs
• references/other.md - Installation des logs pour autres langages - docs
• references/start-here.md - Débuter avec les logs - docs
• references/search.md - Rechercher dans les logs - docs
• references/best-practices.md - Bonnes pratiques de logging - docs
• references/troubleshooting.md - Dépannage des logs - docs
• references/link-session-replay.md - Lier la session replay - docs
• references/debug-logs-mcp.md - Déboguer les logs avec mcp - docs

Chaque référence de plateforme contient la configuration OTLP spécifique, la configuration du SDK et les modèles d'intégration. Trouvez celle qui correspond à votre stack.

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 minimaux : Ajoutez l'export de logs à côté de la logging existante. Ne remplacez pas ou ne restructurez pas le code de logging existant.
• OpenTelemetry : Les logs PostHog utilisent le protocole OpenTelemetry. Configurez un exporteur OTLP pointant vers le point de terminaison d'ingestion de PostHog.
• Logging structuré : Préférez les formats de logs structurés avec propriétés clé-valeur aux messages en texte brut.