Diagnostiquer les enregistrements de session manquants

Quand un utilisateur demande « pourquoi cette session n'a pas été enregistrée ? » ou « pourquoi n'ai-je aucun enregistrement ? », suivez ce workflow pour diagnostiquer systématiquement la cause.

Outils disponibles

Signaux diagnostiques

Le SDK PostHog émet des propriétés diagnostiques sur chaque événement qui expliquent l'état de l'enregistrement. Consultez la référence des signaux diagnostiques pour la liste complète.

Les signaux clés sont :

• $has_recording — si PostHog a un enregistrement stocké pour cette session
• $recording_status — état du SDK : active, buffering, disabled, sampled, paused
• $session_recording_start_reason — pourquoi l'enregistrement a démarré ou non
• $sdk_debug_recording_script_not_loaded — script d'enregistreur bloqué (bloqueur de publicités)
• $sdk_debug_replay_*_trigger_status — états des déclencheurs (URL, événement, drapeau lié)
• $replay_sample_rate — taux d'échantillonnage configuré au moment de la capture

Workflow

Étape 1 — Vérifier si l'enregistrement existe

Si l'utilisateur fournit un ID de session, vérifiez d'abord si un enregistrement existe réellement :

posthog:session-recording-get
{
  "id": "<session_id>"
}

Si cela retourne des données, l'enregistrement existe — le problème est probablement l'interface utilisateur/filtrage, pas la capture. S'il retourne 404, passez au diagnostic de la cause.

Étape 2 — Interroger les signaux diagnostiques des événements

Interrogez l'événement le plus récent de la session pour obtenir les propriétés diagnostiques du SDK :

posthog:execute-sql
SELECT
    properties.$has_recording AS has_recording,
    properties.$recording_status AS recording_status,
    properties.$session_recording_start_reason AS start_reason,
    properties.$sdk_debug_recording_script_not_loaded AS script_not_loaded,
    properties.$sdk_debug_replay_url_trigger_status AS url_trigger,
    properties.$sdk_debug_replay_event_trigger_status AS event_trigger,
    properties.$sdk_debug_replay_linked_flag_trigger_status AS flag_trigger,
    properties.$replay_sample_rate AS sample_rate,
    properties.$sdk_debug_replay_internal_buffer_length AS buffer_length,
    properties.$sdk_debug_replay_flushed_size AS flushed_size,
    properties.$lib AS sdk_library,
    properties.$lib_version AS sdk_version
FROM events
WHERE $session_id = '<session_id>'
ORDER BY timestamp DESC
LIMIT 1

Étape 3 — Diagnostiquer le verdict

Utilisez la référence de la logique de diagnostic pour interpréter les signaux. Les verdicts par ordre de priorité :

1. L'enregistrement existe ($has_recording = true) — l'enregistrement est capturé, le problème est ailleurs
2. Bloqué par publicité (script) ($sdk_debug_recording_script_not_loaded = true) — extension de navigateur bloquant le chargement du script d'enregistreur
3. Désactivé ($recording_status = 'disabled') — replay désactivé dans les paramètres ou la configuration du SDK
4. Déclencheur en attente (les statuts des déclencheurs sont trigger_pending, aucun n'a correspondu) — enregistrement conditionné par un déclencheur qui n'a jamais tiré
5. Échantillonné ($session_recording_start_reason = 'sampled_out') — exclu par le taux d'échantillonnage
6. Buffer vide ($recording_status = 'buffering', longueur du buffer = 0, rien vidé) — initialisé mais aucun snapshot produit
7. Vidage bloqué (la longueur du buffer augmente entre les événements tandis que flushed_size reste à 0) — les snapshots sont produits mais l'endpoint d'ingestion /s/ est bloqué par un bloqueur de publicités ou un proxy inverse mal configuré. La détection de ceci nécessite d'interroger la tendance entre les événements de la session — voir l'exemple 3 dans examples.md
8. Inconnu — les signaux ne correspondent à aucun motif connu

Étape 4 — Vérifier les paramètres au niveau du projet (sans ID de session)

Quand l'utilisateur demande des enregistrements manquants au niveau du projet (pas de session spécifique), interrogez les sessions récentes pour vérifier le motif :

posthog:execute-sql
SELECT
    $session_id,
    properties.$recording_status AS recording_status,
    properties.$session_recording_start_reason AS start_reason,
    properties.$sdk_debug_recording_script_not_loaded AS script_not_loaded,
    properties.$replay_sample_rate AS sample_rate
FROM events
WHERE event = '$pageview'
    AND timestamp > now() - INTERVAL 1 DAY
GROUP BY
    $session_id,
    recording_status,
    start_reason,
    script_not_loaded,
    sample_rate
ORDER BY max(timestamp) DESC
LIMIT 10

Recherchez des motifs :

• Tous disabled → replay est désactivé dans les paramètres du projet
• Tous sampled_out avec taux d'échantillonnage faible → taux d'échantillonnage trop agressif
• Tous script_not_loaded → probablement un problème CSP ou de déploiement, pas juste le bloqueur de publicités d'un utilisateur
• Mélange de statuts → problème par session, creusez dans les détails

Étape 5 — Fournir des recommandations actionnables

Basé sur le verdict, recommandez des actions spécifiques :

Exemples

Consultez les exemples diagnostiques du monde réel montrant comment les combinaisons de signaux correspondent aux verdicts. Utilisez-les pour calibrer votre interprétation des résultats de requête.

Astuces

• Si $lib_version est très ancienne, certains signaux diagnostiques ne seront pas présents. Notez-le à l'utilisateur — mettre à jour le SDK fournira de meilleurs diagnostics.
• Une session peut avoir des événements mais pas d'enregistrement si l'enregistrement a été supprimé en raison de la rétention. Vérifiez l'horodatage de la session par rapport à la période de rétention du projet.
• Si $has_recording est vrai mais que l'utilisateur ne le trouve pas, vérifiez s'il est filtré par durée, seuil d'activité ou filtres de playlist.