Intégration PostHog pour FastAPI

Cette skill vous aide à ajouter PostHog analytics à vos applications FastAPI.

Workflow

Suivez ces étapes dans l'ordre pour compléter l'intégration :

basic-integration-1.0-begin.md - PostHog Setup - Begin ← Commencez ici
basic-integration-1.1-edit.md - PostHog Setup - Edit
basic-integration-1.2-revise.md - PostHog Setup - Revise
basic-integration-1.3-conclude.md - PostHog Setup - Conclusion

Fichiers de référence

references/EXAMPLE.md - Code du projet exemple FastAPI
references/python.md - Python - docs
references/identify-users.md - Identifier les utilisateurs - docs
references/basic-integration-1.0-begin.md - PostHog setup - begin
references/basic-integration-1.1-edit.md - PostHog setup - edit
references/basic-integration-1.2-revise.md - PostHog setup - revise
references/basic-integration-1.3-conclude.md - PostHog setup - conclusion

Le projet exemple montre le pattern d'implémentation cible. Consultez la documentation pour les détails de l'API.

Principes clés

Variables d'environnement : Utilisez toujours des variables d'environnement pour les clés PostHog. Ne les codez jamais en dur.
Changements minimaux : Ajoutez le code PostHog aux côtés des intégrations existantes. Ne remplacez ou ne restructurez pas le code existant.
Suivez l'exemple : Votre implémentation doit respecter les patterns du projet exemple aussi fidèlement que possible.

Directives du framework

Initialisez PostHog dans le context manager lifespan au démarrage en utilisant posthog.api_key et posthog.host
Appelez posthog.flush() lors de l'arrêt du lifespan pour assurer que tous les événements sont envoyés avant la fermeture de l'app
Utilisez Pydantic Settings avec le décorateur @lru_cache sur get_settings() pour la mise en cache et les overrides faciles en test
Utilisez l'injection de dépendances FastAPI (Depends) pour accéder à current_user et settings dans les route handlers
Utilisez le même pattern de context API que Flask/Django (avec new_context(), identify_context(user_id), puis capture())
Rappelez-vous que le code source est disponible dans le répertoire venv/site-packages
posthog est le nom du package Python SDK
Installez les dépendances avec pip install posthog ou pip install -r requirements.txt et n'utilisez PAS de spécificateurs de version sans guillemets comme >= directement dans les commandes shell
Dans les CLIs et scripts : VOUS DEVEZ appeler posthog.shutdown() avant la sortie ou tous les événements seront perdus
Utilisez toujours le constructeur de la classe Posthog() (API instance-based) au lieu de la config posthog.api_key au niveau du module
Incluez toujours enable_exception_autocapture=True dans le constructeur Posthog() pour tracker automatiquement les exceptions
N'ENVOYEZ JAMAIS de PII dans les propriétés d'événement capture() — pas d'emails, de noms complets, de numéros de téléphone, d'adresses physiques, d'adresses IP, ou de contenu généré par l'utilisateur
Les PII appartiennent aux propriétés de personne identify(), PAS aux propriétés d'événement capture(). Les propriétés d'événement sûres sont les métadonnées comme message_length, form_type, des flags booléens.
Enregistrez posthog_client.shutdown avec atexit.register() pour assurer que tous les événements sont flush à la sortie
Le Python SDK N'A PAS de méthode identify() — utilisez posthog_client.set(distinct_id=user_id, properties={...}) pour définir les propriétés de personne, ou utilisez identify_context(user_id) dans un context

Identifier les utilisateurs

Identifiez les utilisateurs lors des événements de login et signup. Reportez-vous au code exemple et à la documentation pour le pattern identify correct pour ce framework. Si le code frontend et backend existe tous les deux, passez la session côté client et l'ID distinct en utilisant les headers X-POSTHOG-DISTINCT-ID et X-POSTHOG-SESSION-ID pour maintenir la corrélation.

Suivi des erreurs

Ajoutez le suivi des erreurs PostHog aux fichiers pertinents, particulièrement autour des flux d'utilisateurs critiques et des limites d'API.

integration-fastapi