posthog/ai-plugin

diagnosing-missing-recordings

Diagnoses why a session recording is missing or was not captured.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/posthog/ai-plugin --skill diagnosing-missing-recordings

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Diagnosing missing session recordings

When a user asks "why wasn't this session recorded?" or "why don't I have any recordings?", follow this workflow to systematically diagnose the cause.

Available tools

ToolPurpose
posthog:execute-sqlQuery session event properties for diagnostic signals
posthog:session-recording-getCheck if a recording actually exists for the session
posthog:query-session-recordings-listSearch for recordings matching criteria

Diagnostic signals

The PostHog SDK emits diagnostic properties on every event that explain the recording state. See the diagnostic signals reference for the full list.

The key signals are:

  • $has_recording — whether PostHog has a stored recording for this session
  • $recording_status — SDK state: active, buffering, disabled, sampled, paused
  • $session_recording_start_reason — why recording started or didn't
  • $sdk_debug_recording_script_not_loaded — recorder script blocked (ad blocker)
  • $sdk_debug_replay_*_trigger_status — trigger states (URL, event, linked flag)
  • $replay_sample_rate — configured sample rate at capture time

Workflow

Step 1 — Check if the recording exists

If the user provides a session ID, first check whether a recording actually exists:

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

If this returns data, the recording exists — the issue is likely UI/filtering, not capture. If it returns 404, proceed to diagnose why.

Step 2 — Query diagnostic signals from events

Query the most recent event for the session to get SDK diagnostic properties:

sql
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

Step 3 — Diagnose the verdict

Use the diagnosis logic reference to interpret the signals. The verdicts in priority order:

  1. Recording exists ($has_recording = true) — recording is captured, issue is elsewhere
  2. Ad blocked (script) ($sdk_debug_recording_script_not_loaded = true) — browser extension blocking the recorder script from loading
  3. Disabled ($recording_status = 'disabled') — replay turned off in settings or SDK config
  4. Trigger pending (trigger statuses are trigger_pending, none matched) — recording gated on trigger that never fired
  5. Sampled out ($session_recording_start_reason = 'sampled_out') — excluded by sample rate
  6. Buffering empty ($recording_status = 'buffering', buffer length = 0, nothing flushed) — initialized but no snapshots produced
  7. Flush blocked (buffer length climbs across events while flushed_size stays at 0) — snapshots are produced but the /s/ ingestion endpoint is blocked by an ad blocker or misconfigured reverse proxy. Detecting this requires querying the trend across the session's events — see example 3 in examples.md
  8. Unknown — signals don't match a known pattern

Step 4 — Check project-level settings (if no session ID)

When the user asks about recordings missing project-wide (no specific session), query for recent sessions to check the pattern:

sql
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

Look for patterns:

  • All disabled → replay is turned off in project settings
  • All sampled_out with low sample rate → sample rate too aggressive
  • All script_not_loaded → likely a CSP or deployment issue, not just one user's ad blocker
  • Mix of statuses → per-session issue, dig into specifics

Step 5 — Provide actionable recommendations

Based on the verdict, recommend specific actions:

VerdictRecommendation
Ad blockedUser's browser extension is blocking rrweb. Suggest trying without ad blocker, or using a proxy/custom domain for the recorder script
DisabledCheck project replay settings — recording may be turned off. Link to Settings > Session replay
Trigger pendingThe configured trigger (URL pattern, event, or feature flag) never matched. Review trigger configuration
Sampled outIncrease the sample rate in project settings, or use a trigger to guarantee capture for important sessions
Buffering emptyPage closed before first snapshot. Common with very short sessions or single-page navigations. Consider lowering minimum duration
UnknownDirect user to troubleshooting docs: https://posthog.com/docs/session-replay/troubleshooting

Examples

See real-world diagnostic examples showing how signal combinations map to verdicts. Use these to calibrate your interpretation of query results.

Tips

  • If $lib_version is very old, some diagnostic signals won't be present.

Note this to the user — upgrading the SDK will provide better diagnostics.

  • A session might have events but no recording if the recording was deleted due to retention.

Check the session's timestamp against the project's retention period.

  • If $has_recording is true but the user can't find it, check if it's filtered out

by duration, activity threshold, or playlist filters.

Related skills

  • `diagnosing-sdk-health` — an outdated SDK is a common root cause and blunts the diagnostic signals
  • `finding-sessions-to-watch` — once capture works, pick the sessions worth watching
  • `investigating-replay` — analyze the recording once it exists

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills
posthog
공식

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.

1시간 설치 수
2
GitHub Stars
98
업데이트
11월 6일
posthog
공식

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

1시간 설치 수
2
GitHub Stars
98
업데이트
11월 6일
posthog
공식

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.

1시간 설치 수
2
GitHub Stars
98
업데이트
11월 6일
posthog
공식

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.

1시간 설치 수
2
GitHub Stars
98
업데이트
11월 6일