posthog/ai-plugin

finding-replay-for-issue

Finds the most informative session recording linked to an error tracking issue.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/posthog/ai-plugin --skill finding-replay-for-issue

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Finding the best replay for an error tracking issue

When a user says "show me a replay for this error" or "find a recording for issue X", the goal isn't just any linked session — it's the one that best shows what led to the error. Popular issues can have hundreds of linked sessions, and most are crash-only fragments or duplicate occurrences. This skill picks the most useful one.

Available tools

ToolPurpose
posthog:query-error-tracking-issueGet issue details (fingerprint, status, volume)
posthog:execute-sqlQuery exception events to find linked sessions
posthog:query-session-recordings-listFetch recording metadata for candidate sessions
posthog:session-recording-getGet full details for the selected recording
posthog:vision-observations-listCheck for an existing Replay Vision AI summary
posthog:vision-scanners-listFind summarizer scanners (scanner_type=summarizer)
posthog:vision-scanners-scan-sessionRun a summarizer scanner on the recording (optional, slow)

Workflow

Step 1 — Get the issue details

Fetch the error tracking issue to understand what you're looking for:

json
posthog:query-error-tracking-issue
{
  "issueId": "<issue_id>"
}

Note the issue's fingerprint, name, and description — you'll need the fingerprint to find linked sessions.

Step 2 — Find sessions with this error

Query exception events to get session IDs where this error occurred. Order by recency and include basic context:

sql
posthog:execute-sql
SELECT
    $session_id AS session_id,
    count() AS occurrences,
    min(timestamp) AS first_seen,
    max(timestamp) AS last_seen,
    any(properties.$current_url) AS url
FROM events
WHERE event = '$exception'
    AND properties.$exception_fingerprint = '<fingerprint>'
    AND $session_id IS NOT NULL
    AND timestamp > now() - INTERVAL 30 DAY
GROUP BY session_id
ORDER BY last_seen DESC
LIMIT 20

This gives you up to 20 candidate sessions. More candidates means better selection.

Step 3 — Rank the candidates

Fetch recording metadata for the candidate sessions to rank them:

json
posthog:query-session-recordings-list
{
  "session_ids": ["<id1>", "<id2>", "<id3>", ...],
  "date_from": "-30d"
}

Pick the best recording by filtering out bad candidates, then ranking what's left:

Filter out:

  • Sessions under 10 seconds (crash-only fragments, no pre-error context)
  • Sessions over 1 hour (too much data to load, error is a needle in a haystack)

Rank by:

  1. Sweet-spot duration — 2-15 minutes is ideal. Long enough to show the user's

journey before the error, short enough to be practical to watch or summarize.

  1. Active time ratio — compare active_seconds to recording_duration. A 20-minute

recording with 10 seconds of activity is mostly idle tabs — the user walked away. Prefer sessions where active_seconds / recording_duration is above 0.3 (30%).

  1. Activity score — higher activity_score means the user was actively interacting,

not idle. More interesting to watch.

  1. Recency — more recent sessions reflect current app behavior.

Step 4 — Present the finding

Fetch full details for the selected recording:

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

Present to the user:

  • The recording with a link to watch it
  • Why this one — briefly explain the selection ("longest session with the error,

user was browsing 3 pages before hitting it")

  • Pre-error context — what pages the user visited and key actions before the exception,

derived from the events query in step 2 (the url and first_seen columns)

  • Error frequency — how many times the error occurred in this session

Optional: AI summary via Replay Vision

If the user wants a narrative summary without watching, use Replay Vision — "check-then-scan", since a scanner can only observe a given session once.

  1. Check for an existing summary on the selected recording:
json
   posthog:vision-observations-list
   {
     "session_id": "<best_recording_id>"
   }

If an observation has scanner_snapshot.scanner_type summarizer and status succeeded, read scanner_result.model_output (title, summary, intent, outcome, friction_points, keywords) — done.

  1. Find a summarizer scanner if none exists:
json
   posthog:vision-scanners-list
   {
     "scanner_type": "summarizer"
   }

One → use it. More than one → ask the user which (show name + prompt). None → offer to create one via the creating-replay-vision-scanners skill.

  1. Scan the recording with the chosen scanner (async, several minutes):
json
   posthog:vision-scanners-scan-session
   {
     "id": "<scanner_id>",
     "session_id": "<best_recording_id>"
   }
  1. Retrieve by polling vision-observations-list until succeeded.

Tips

  • If all candidate sessions are very short (<10 seconds), the error likely crashes

the page immediately. Note this — it's useful context even without a long replay.

  • When the issue has very few linked sessions (<3), skip the ranking and just present

what's available with a note about the small sample.

  • If $session_id is null on many exception events, session replay may not be enabled

for the affected users. Mention this as a possible gap.

  • Replay Vision has no per-call focus parameter — a summarizer scanner's focus

comes from its own prompt. For error-focused summaries, prefer (or create) a summarizer scanner whose prompt targets error/exception context rather than the whole session.

Related skills

  • `investigating-error-issue` — the quantitative side: volume, breakdowns, and stack traces for the same issue
  • `investigating-replay` — deep-dive one of the linked sessions
  • `diagnosing-missing-recordings` — when exception events have no $session_id or the linked recordings are gone

按任务相关推荐

来自同一仓库

更多 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日