Déboguer la lecture locale de session

Quand un développeur dit « la lecture locale ne fonctionne pas » ou « les enregistrements ne s'affichent pas », parcourez ces couches dans l'ordre. Le pipeline de lecture locale a plusieurs composants et les défaillances sont généralement silencieuses.

Guide rapide des symptômes

Le pipeline de lecture locale

Browser SDK  →  endpoint /s (proxy Caddy :8000)
             →  capture-replay (Rust, :3306)
             →  Kafka (topic session_recording_snapshot_item_events)
             →  ingestion-sessionreplay (Node, :6740, PLUGIN_SERVER_MODE=recordings-blob-ingestion-v2)
             →  SeaweedFS (stockage blob, :8333)
             →  recording-api (Node, :6741, PLUGIN_SERVER_MODE=recording-api)
             →  Frontend

Une rupture à n'importe quel point de cette chaîne signifie aucun enregistrement dans l'interface. L'approche diagnostique est de trouver où la chaîne se casse.

Étape 1 — Le SDK essaie-t-il même d'enregistrer ?

Demandez au développeur d'ouvrir l'onglet Network de DevTools et de filtrer par /s.

S'il n'y a aucun appel /s du tout : Le SDK n'essaie pas d'envoyer les données d'enregistrement. Enquêtez sur les causes côté client :

• Triggers configurés dans les paramètres du projet. Si des triggers URL, des triggers événement ou des triggers linked flag sont configurés, l'enregistrement ne démarre que lorsqu'un trigger se déclenche. C'est la cause la plus courante pour les développeurs qui testent les fonctionnalités de triggers. Vérifiez les paramètres Session replay dans l'interface locale (Paramètres du projet > Session replay). Supprimez ou ajustez les triggers pour permettre au enregistrement de démarrer.
• Enregistrement désactivé dans les paramètres du projet. Session replay peut être désactivé.
• Taux d'échantillonnage trop bas. Si $replay_sample_rate est < 1,0, les sessions peuvent être écartées.
• SDK non initialisé avec l'enregistrement. Vérifiez l'initialisation PostHog de l'app locale — session_recording ne doit pas être explicitement désactivé.
• Mauvais hôte PostHog. L'app locale doit pointer vers http://localhost:8000 (ou où que le proxy Caddy local s'exécute).
• Ad blocker. Même en développement local, les extensions du navigateur peuvent bloquer le script recorder ou l'endpoint /s.
• Le script recorder n'a pas pu être chargé (erreur MIME type / CORS). La console du navigateur peut afficher MIME type ('text/html') is not executable pour posthog-recorder.js ou une erreur CORS pour lazy-recorder.js. Cela signifie que Django sert une page HTML (généralement la redirection de connexion) au lieu du fichier JS — les scripts recorder statiques sont périmés ou manquants. Voir recorder script build failure.

Si des appels /s se produisent avec des réponses 200 : Le SDK enregistre et capture reçoit les données. La rupture est en aval — passez à l'Étape 2.

Si les appels /s retournent des erreurs (4xx/5xx) : Le service capture peut être arrêté ou mal configuré. Vérifiez capture-replay dans phrocs.

Étape 2 — Les processus requis s'exécutent-ils ?

Vérifiez que ces processus phrocs s'exécutent et sont sains. Un processus « en cours d'exécution » qui n'a jamais produit de sortie après tsx watch src/index.ts est effectivement mort.

Processus clés et leurs ports

Vérifiez avec :

lsof -nP -i :3306 -i :6740 -i :6741

Si les ports n'écoutent pas : Les processus n'ont pas démarré ou sont bloqués. Voir common failures.

Si les ports écoutent : Les processus du pipeline s'exécutent. Passez à l'Étape 3.

Dépendances Docker

Ces conteneurs Docker doivent s'exécuter et être sains :

Vérifiez avec :

docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "kafka|db|redis7|clickhouse|seaweed"

Tous doivent afficher (healthy) sauf seaweedfs qui n'a pas de vérification de santé. Si seaweedfs-main est manquant, le profil Docker replay n'est peut-être pas actif — vérifiez la sortie du processus phrocs docker-compose pour --profile replay.

Étape 3 — Les données circulent-elles par Kafka ?

Si capture-replay s'exécute et reçoit des appels /s, les données doivent arriver sur le topic Kafka session_recording_snapshot_item_events. Vérifiez l'interface Kafka à http://localhost:8080 (si l'intent debug_tools est activé) ou utilisez kcat :

kcat -b localhost:9092 -t session_recording_snapshot_item_events -C -c 5 -e

Si le topic est vide ou n'existe pas : capture-replay n'écrit pas dans Kafka. Vérifiez ses logs phrocs pour les erreurs de connexion Kafka.

Si les données sont sur le topic mais les enregistrements n'apparaissent pas : ingestion-sessionreplay ne consomme pas. Vérifiez s'il est bloqué, crashé ou si un processus orphelin verrouille le groupe de consommateurs (voir les défaillances courantes).

Étape 4 — Vérifier SeaweedFS

L'ingestion écrit les blobs d'enregistrement dans SeaweedFS. Vérifiez qu'il est accessible :

curl -s http://localhost:8333/ | head -5

La variable d'environnement SESSION_RECORDING_V2_S3_ENDPOINT doit être configurée correctement. Dans bin/start, elle remonte par défaut à http://seaweedfs:8333 (le nom d'hôte Docker). Les processus hôte résolvent cela via la mise en réseau Docker.

Référence des défaillances courantes

Voir common failures pour le diagnostic détaillé de :

• Processus Node orphelins verrouillant les groupes de consommateurs Kafka
• Processus bloqués à bin/wait-for-docker
• tsx watch étouffant silencieusement les crashes
• Conflits de ports entre Docker et les processus hôte
• Contention du verrou de build Cargo au démarrage