Diagnostic de la symbolicisation des stack traces

La symbolicisation est le nom multiplateforme de ce que la recherche source-map JavaScript, la résolution de décalage de fonction Hermes, le démunification Proguard / R8 et la recherche adresse-vers-ligne dSYM font tous — transformer un frame minifié ou obfusqué en fichier, fonction et ligne lisibles.

Travaillez dans le build de l'utilisateur et les ensemble de symboles PostHog comme un pipeline : config de build -> artefacts de symboles générés (source maps JavaScript, maps Hermes, mappages Proguard ou bundles dSYM) -> ensemble de symboles uploadé dans PostHog -> frame d'erreur capturé. La plupart des défaillances deviennent évidentes une fois que ces quatre éléments sont vérifiés dans l'ordre.

Plateformes

L'étape 3 du flux (recherche d'ensemble de symboles dans PostHog) est identique sur toutes les plateformes — posthog-cli symbol-sets extract gère les quatre types de conteneur. Les étapes 1, 2 et les modes de défaillance spécifiques à la plateforme vivent dans la référence par plateforme.

Flux

Étape 1 - Trouvez comment les données de symboles sont produites et uploadées

Examinez les scripts de build du dépôt de l'application et la config d'upload PostHog. Confirmez quel package PostHog gère l'upload (@posthog/rollup-plugin, @posthog/webpack-plugin, @posthog/nextjs-config, @posthog/nuxt, ou posthog-cli direct) et quel répertoire ou asset il traite. Voir la référence plateforme pour l'inspection config spécifique à l'outil de build.

Pour le débogage, préférez un build où les artefacts de symboles restent sur disque après l'upload afin de pouvoir comparer les artefacts locaux à ce que PostHog a reçu. Exemple JavaScript avec le plugin Vite (la référence plateforme couvre le paramètre équivalent pour d'autres outils de build) :

sourcemaps: {
  enabled: true,
  deleteAfterUpload: false,
}

Étape 2 - Construisez et inspectez les artefacts locaux

Exécutez le build de production qui upload les symboles, puis inspectez les fichiers émis localement. Les fichiers exacts et l'invocation helper diffèrent par plateforme — voir la référence plateforme pour la commande helper, la forme de fichier attendue et les pièges courants au moment de la build (notamment les faux positifs de mappages vides qui ressemblent à des bugs d'upload mais sont en réalité des problèmes de config bundler).

Si les artefacts locaux semblent déjà incorrects, corrigez le build avant de déboguer l'upload PostHog.

Étape 3 - Vérifiez les ensemble de symboles dans PostHog

Recherchez l'ensemble de symboles dont le ref correspond au chunk_id du frame capturé en utilisant les outils MCP dédiés — ils gèrent l'auth, la portée du projet et la pagination automatiquement :

• posthog:error-tracking-symbol-sets-list avec ref=<chunk_id> retourne la ligne correspondante.
• posthog:error-tracking-symbol-sets-retrieve avec l'ID retourne la même forme (et confirme les permissions).
• posthog:error-tracking-symbol-sets-download-retrieve retourne une URL présignée d'une heure pointant vers le fichier de données de symboles uploadé. Téléchargez-la immédiatement ; ne renvoyez pas l'URL sauf si l'utilisateur le demande explicitement.

Si l'accès MCP n'est pas disponible, les mêmes données sont dans Paramètres du projet > Suivi des erreurs > Ensemble de symboles dans l'UI PostHog.

Interprétez la ligne :

• ref doit correspondre au frame capturé chunk_id.
• La mise à jour de last_used signifie que PostHog a trouvé et chargé cet ensemble de symboles. Cela ne garantit pas que le frame s'est résolu.
• has_uploaded_file: false signifie que l'upload ne s'est pas terminé.
• Un failure_reason non-null signifie que PostHog n'a pas pu parser ou charger les données de symboles uploadées.

Le fichier téléchargé est un conteneur de données de symboles PostHog (payload encodé Rust compressé), pas du JSON simple. Extrayez-le avec posthog-cli :

posthog-cli symbol-sets extract symbolset.bin -o ./extracted
# ou, sans installer globalement :
#   npx @posthog/cli symbol-sets extract symbolset.bin -o ./extracted
#   bunx @posthog/cli symbol-sets extract symbolset.bin -o ./extracted

posthog-cli symbol-sets extract gère les quatre types d'ensemble de symboles (source-and-map, hermes, proguard, dSYM) et écrit les fichiers extraits dans le répertoire de sortie. Une fois extraits, résumez en utilisant le helper de la référence plateforme.

Étape 4 - Comparez les fichiers locaux, uploadés et servis

Utilisez la location de défaillance pour décider quoi comparer :

• Artefact local vide et artefact uploadé vide : l'outil de build a émis des symboles inutilisables.
• Artefact local valide mais artefact uploadé vide : le traitement de l'upload a sélectionné ou emballé les mauvaises données.
• Artefact uploadé valide mais la stack de production reste minifiée ou obfusquée : comparez les bytes binaires déployés au binaire qui a été uploadé avec les symboles.
• Token not found : PostHog a chargé les données de symboles mais la position générée capturée ne correspondait à aucun token dans l'artefact uploadé. Généralement un indicateur de binaire changé après l'upload, capture de ligne / colonne incorrecte (JavaScript) ou décalage de frame incorrect (Hermes / dSYM), ou un bug de couverture de symboles.

Étape 5 - Corrigez la couche la plus probable

Correctifs agnostiques à la plateforme :

• Uploadez les symboles après que la sortie du build final existe, pas avant qu'une étape ultérieure la réécrive.
• Utilisez le dernier plugin de build PostHog et posthog-cli.
• Ré-uploadez les assets modifiés intentionnellement quand le même ref a été précédemment uploadé avec un contenu différent.
• Supprimez les transformations au moment du déploiement (minify CDN, réécrits edge, compression) qui modifient le binaire servi après l'upload.

Les correctifs spécifiques à la plateforme vivent dans la référence plateforme.

Vérifications de frame capturé

À partir d'un événement d'erreur PostHog affecté, collectez un frame d'application minifié :

• filename
• line ou lineno
• column ou colno
• function
• chunk_id (ou l'équivalent plateforme du ref de l'ensemble de symboles)
• tout resolve_failure, particulièrement Token not found

Le frame filename doit correspondre à l'URL binaire déployée. Le chunk_id doit correspondre au ref de l'ensemble de symboles. La position générée capturée doit pointer dans le même binaire qui a été uploadé avec les données de symboles.

Matrice de défaillance (multiplateforme)

Les modes de défaillance spécifiques à la plateforme (mappages vides, sourcesContent manquant, décalage de fonction Hermes incompatible, dérive de nom de classe Proguard, UUID dSYM incompatible) vivent dans la référence plateforme.