posthog/ai-plugin

diagnosing-stacktrace-symbolication

Help users debug PostHog Error Tracking stack-trace symbolication for any supported platform — JavaScript/TypeScript web, React Native (Hermes), Android (Proguard / R8), or iOS / macOS (dSYM).

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/posthog/ai-plugin --skill diagnosing-stacktrace-symbolication

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Diagnosing stack-trace symbolication

Symbolication is the cross-platform name for what JavaScript source-map lookup, Hermes function-offset resolution, Proguard / R8 demangling, and dSYM address-to-line lookup all do — turn a minified or obfuscated frame back into a readable file, function, and line.

Work through the user's build and PostHog symbol sets as one pipeline: build config -> generated symbol artifacts (JavaScript source maps, Hermes maps, Proguard mappings, or dSYM bundles) -> uploaded symbol set in PostHog -> captured error frame. Most failures become obvious once those four pieces are checked in order.

Platforms

PlatformSymbol-data typeReference
JavaScript / TypeScript websource-and-mapjavascript.md
React Native (Hermes)hermescoming soon
Android (Proguard / R8)proguardcoming soon
iOS / macOS (dSYM)apple-dsymcoming soon

Step 3 of the workflow (symbol-set lookup in PostHog) is identical across platforms — posthog-cli symbol-sets extract handles all four container types. Steps 1, 2, and the platform-specific failure modes live in the per-platform reference.

Workflow

Step 1 - Find how symbol data is produced and uploaded

Look at the app repo's build scripts and PostHog upload config. Confirm which PostHog package handles the upload (@posthog/rollup-plugin, @posthog/webpack-plugin, @posthog/nextjs-config, @posthog/nuxt, or direct posthog-cli) and which directory or asset it processes. See the platform reference for build-tool-specific config inspection.

For debugging, prefer a build where symbol artifacts remain on disk after upload so you can compare local artifacts against what PostHog received. JavaScript example with the Vite plugin (the platform reference covers the equivalent setting for other build tools):

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

Step 2 - Build and inspect local artifacts

Run the production build that uploads symbols, then inspect the emitted files locally. The exact files and helper invocation differ per platform — see the platform reference for the helper command, expected file shape, and common build-time pitfalls (notably empty-mappings false positives that look like upload bugs but are actually bundler config issues).

If local artifacts already look wrong, fix the build before debugging the PostHog upload.

Step 3 - Check symbol sets in PostHog

Look up the symbol set whose ref matches the captured frame's chunk_id using the dedicated MCP tools — they handle auth, project scoping, and pagination automatically:

  • posthog:error-tracking-symbol-sets-list with ref=<chunk_id> returns the matching row.
  • posthog:error-tracking-symbol-sets-retrieve with the ID returns the same shape (and confirms permissions).
  • posthog:error-tracking-symbol-sets-download-retrieve returns a one-hour presigned URL pointing at the uploaded

symbol-data file. Download it immediately; do not echo the URL back unless the user explicitly asks.

If MCP access is not available, the same data is in Project settings > Error tracking > Symbol sets in the PostHog UI.

Interpret the row:

  • ref must match the captured frame chunk_id.
  • last_used updating means PostHog found and loaded that symbol set. It does not guarantee the frame resolved.
  • has_uploaded_file: false means the upload did not complete.
  • A non-null failure_reason means PostHog could not parse or load the uploaded symbol data.

The downloaded file is a PostHog symbol-data container (compressed Rust-encoded payload), not plain JSON. Extract it with posthog-cli:

bash
posthog-cli symbol-sets extract symbolset.bin -o ./extracted
# or, without installing globally:
#   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 handles all four symbol-set types (source-and-map, hermes, proguard, dSYM) and writes the extracted files into the output directory. Once extracted, summarize using the platform reference's helper.

Step 4 - Compare local, uploaded, and served files

Use the failure location to decide what to compare:

  • Local artifact empty and uploaded artifact empty: build tool emitted unusable symbols.
  • Local artifact valid but uploaded artifact empty: upload processing selected or packed the wrong data.
  • Uploaded artifact valid but production stack stays minified or obfuscated: compare deployed binary bytes to the

binary that was uploaded with the symbols.

  • Token not found: PostHog loaded the symbol data but the captured generated position did not match any token in

the uploaded artifact. Usually points to a changed binary after upload, wrong line / column capture (JavaScript) or wrong frame offset (Hermes / dSYM), or a symbol-coverage bug.

Step 5 - Fix the most likely layer

Platform-neutral fixes:

  • Upload symbols after the final build output exists, not before a later step rewrites it.
  • Use the latest PostHog build plugin and posthog-cli.
  • Re-upload changed assets intentionally when the same ref was previously uploaded with different content.
  • Remove deployment-time transforms (CDN minify, edge rewrites, compression) that change the served binary after

upload.

Platform-specific fixes live in the platform reference.

Captured frame checks

From an affected PostHog error event, collect one minified application frame:

  • filename
  • line or lineno
  • column or colno
  • function
  • chunk_id (or platform-equivalent symbol-set ref)
  • any resolve_failure, especially Token not found

The frame filename should match the deployed binary URL. The chunk_id should match the symbol set ref. The captured generated position should point into the same binary that was uploaded with the symbol data.

Failure matrix (cross-platform)

EvidenceLikely causeNext check
No chunk_id on framesChunk ID injection missing or SDK frame parser did not map the filenameInspect deployed binary and raw frame filenames.
Symbol set row missingUpload went to another PostHog project/host or skipped this assetCompare plugin projectId, host, and ref.
has_uploaded_file: falseUpload did not finishCheck build logs; compare posthog-cli output to the symbol set row.
Non-null failure_reasonPostHog could not parse the uploaded symbol dataDownload via Step 3 and inspect the extracted contents.
Uploaded artifact valid, deployed binary differsDeployment/CDN/post-build transform changed the binary after uploadCompare deployed bytes to local build output.
Token not foundCaptured position has no token in the uploaded symbol dataVerify captured position, deployed binary identity, and symbol-data coverage.

Platform-specific failure modes (empty mappings, missing sourcesContent, Hermes function-offset mismatch, Proguard class-name drift, dSYM UUID mismatch) live in the platform reference.

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills
posthog
Offiziell

exploring-llm-costs

Investigate LLM spend in PostHog — total cost over time, cost by model, provider, user, trace, or custom dimension, token and cache-hit economics, and cost regressions. Use when the user asks "how much are we spending on LLMs?", "which model / user / feature is most expensive?", "why did cost spike?", wants to build a cost dashboard or alert, or pastes a trace URL and asks about its cost.

Installationen / 1h
2
GitHub Stars
98
Aktualisiert
6. Nov.
posthog
Offiziell

exploring-llm-traces

Debug and inspect LLM/AI agent traces using PostHog's MCP tools. Use when the user pastes a trace or session URL (e.g. /ai-observability/traces/ or /ai-observability/sessions/ ), asks to debug a trace, figure out what went wrong, check if an agent used a tool correctly, verify context/files were surfaced, inspect subagent behavior, investigate LLM decisions, or analyze token usage and costs. Also use when raw SQL/HogQL against events.properties.$aiinput / $aioutputchoices returns empty — message

Installationen / 1h
2
GitHub Stars
98
Aktualisiert
6. Nov.
posthog
Offiziell

instrument-integration

Add PostHog SDK integration to your application. Use when setting up PostHog for the first time or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration for any framework.

Installationen / 1h
2
GitHub Stars
98
Aktualisiert
6. Nov.
posthog
Offiziell

investigating-error-issue

Investigates a single PostHog error tracking issue end-to-end. Use when the user provides an issue ID or pastes an issue URL (/error-tracking/ ) and wants to understand the error — who it affects, what triggers it, when it started, whether it correlates with a release, browser, OS, or feature flag, and what the next step should be. Pulls aggregated metrics, sample exception events, segment breakdowns, linked replays, and synthesizes a hypothesis-grade summary in one pass.

Installationen / 1h
2
GitHub Stars
98
Aktualisiert
6. Nov.