mongo-ai/posthog-session-replay-diagnosis

Session replay diagnosis workflow

Before you diagnose: fetch live docs

1. Run docs-search with the platform + customer's primary symptom
2. If SDK-specific: run Context7 query-docs for that SDK's config reference
3. If potential known bug: run gh search issues on the relevant repo
4. Use the fetched docs as your primary reference — NOT the steps below

The steps below are a diagnostic FRAMEWORK (what questions to ask, in what order). The docs responses are the CONTENT (current answers, version requirements, config details).

Step 0: Determine platform

Before running any steps, classify the platform from ticket context:

• Web (posthog-js, browser) → proceed to Web Replay Workflow
• iOS (posthog-ios, Swift, SwiftUI, React Native on iOS) → jump to Mobile Replay Workflow
• Android (posthog-android, Kotlin, React Native on Android) → jump to Mobile Replay Workflow
• Flutter (posthog-flutter) → jump to Mobile Replay Workflow

If unclear, ask the customer or check $lib in recent events.

---

Web Replay Workflow

Goal

Identify whether replay issues are caused by:

• outdated SDK / missing extension
• dynamic script loading blocked
• CSP / CORS / stylesheet restrictions
• reverse proxy gaps / ad blockers
• identify/filtering expectations mismatch
• framework-specific browser issues
• domain / trigger configuration mistakes

Step 1: Fetch current web replay troubleshooting docs

Run docs-search("session replay troubleshooting recordings not showing")

Use the response as your primary checklist. Extract:

• Current SDK version requirements
• Config flags that disable recording
• CSP/blocker guidance
• URL trigger vs deprecated settings

Step 2: Check SDK version and source

Query recent web events for $lib_version.

SELECT properties.$lib, properties.$lib_version, count()
FROM events
WHERE distinct_id = '{distinct_id}'
  AND timestamp > now() - interval 7 day
GROUP BY properties.$lib, properties.$lib_version
ORDER BY count() DESC;

Compare against the version requirements from the docs response in Step 1.

Step 3: Determine capture vs playback problem

Separate:

• "recordings not being created" → Step 4
• "recordings exist but look broken" → Step 5

These are different problems.

Step 4: For recordings not being captured

Cross-reference the docs-search checklist with the customer's setup. Key areas to investigate:

• Recording disabled in config
• Lazy-loaded replay dependencies blocked
• CSP blocking dynamic scripts
• Ad/tracking blockers blocking PostHog
• Missing reverse proxy
• URL trigger / domain control misconfiguration

If reverse proxy is relevant, run: docs-search("reverse proxy setup PostHog")

Step 5: For broken-looking replays

Run docs-search("session replay broken blank CORS stylesheet")

Key areas to investigate:

• CORS for assets/fonts
• Stylesheet access issues
• crossorigin attribute on stylesheets
• Framework-specific asset import issues

Step 6: Filtering / identity expectations

If the complaint is "can't filter recording by user/page/cohort":

• verify identify flow
• verify relevant properties exist
• check cohort/calculation status if relevant
• note that backend-only events won't create replay/session correlation the same way as web SDK events

Step 7: Escalate to site inspection if justified

Only if:

• public URL exists
• browser evidence is likely useful
• issue is browser SDK related

---

Mobile Replay Workflow (iOS / Android / Flutter)

Mobile session replay uses a fundamentally different architecture than web: screenshot-based capture (not DOM mutation recording). This means different failure modes.

Step M0: Fetch current mobile replay docs + known issues

Run in parallel:

1. docs-search("{platform} session replay troubleshooting")
2. gh search issues --repo PostHog/posthog-{sdk} "session replay {symptom}" --limit 10
3. For architecture questions: DeepWiki ask_question("PostHog/posthog-{sdk}", "How does the session replay screenshot capture and masking pipeline work?")

Step M1: Classify the mobile symptom

• Performance / OOM / crashes → Step M2
• Recordings missing entirely → Step M3
• Recordings exist but masking is wrong → Step M4
• Recordings exist but visual quality is poor → Step M5

Step M2: Performance / memory / OOM issues

This is the most common mobile replay complaint. The screenshot capture pipeline is the bottleneck.

Architecture context (verify via DeepWiki if stale)

iOS screenshot mode typically works as:

1. Full-window screenshot captured via UIGraphicsImageRenderer
2. View hierarchy traversed to find maskable elements
3. Masking applied by creating a second image with sensitive areas obscured
4. Result encoded and batched for upload

Each cycle may create multiple full-resolution bitmaps. On high-res devices this can consume significant memory per snapshot cycle.

IMPORTANT: Verify this architecture is still accurate by running: DeepWiki ask_question("PostHog/posthog-ios", "session replay screenshot capture memory management")

Search for known issues

Run: gh search issues --repo PostHog/posthog-{sdk} "replay memory OR OOM OR performance OR crash" --limit 10

Check issue status (open/closed), linked PRs, and any experimental branches.

Gather from customer

• SDK version (check against latest release via gh release list)
• Device model(s) and OS version(s)
• Session replay config (especially screenshot mode, throttle delay, masking options)
• Memory profiler trace if available
• Whether issue occurs in wireframe mode or only screenshot mode

Workarounds

Fetch current workarounds: docs-search("{platform} session replay performance workaround")

Common patterns (verify against docs response):

1. Increase throttle delay to reduce capture frequency
2. Reduce masking scope
3. Switch to wireframe mode if feasible
4. Sample replay sessions (enable for subset of users)
5. Disable replay on specific screens with heavy rendering

Step M3: Mobile recordings not captured

Run docs-search("{platform} session replay setup enable")

Key areas to investigate:

• Session replay enabled in config
• SDK version supports mobile replay (fetch minimum from docs)
• Feature flag for replay enabled in project settings
• /decide endpoint response includes session recording
• No conflicting config

Step M4: Masking issues on mobile

Run docs-search("{platform} session replay masking configuration")

Key areas to investigate:

• Which masking options are enabled
• Custom masking modifiers in use
• Known masking bugs (search GitHub issues)
• Framework-specific masking behavior (SwiftUI, Jetpack Compose, Flutter widgets)

Step M5: Visual quality issues

Run docs-search("{platform} session replay quality black rectangles")

Key areas to investigate:

• Screenshot rendering timing (afterScreenUpdates behavior)
• Image encoding format and compression
• Screenshot scale factor settings
• Async-loaded image capture timing

When to escalate

Escalate to engineering if:

• OOM crash is confirmed and workarounds are insufficient
• The customer's use case requires screenshot mode but performance is unacceptable
• New crash signatures not matching known issues