diagnosing-missing-recordings

诊断缺失的会话录制

当用户询问“为什么没有录制这个会话？”或“为什么我没有任何录制内容？”时， 请遵循此工作流，系统地诊断原因。

可用工具

工具	用途
posthog:execute-sql	查询会话事件属性，以获取诊断信号
posthog:session-recording-get	检查该会话是否确实存在录制内容
posthog:query-session-recordings-list	搜索符合条件的录制内容

诊断信号

PostHog SDK 会在每个事件上发出诊断属性，用于说明录制状态。 完整列表请参阅诊断信号参考。

主要信号包括：

• $has_recording — PostHog 是否存储了该会话的录制内容
• $recording_status — SDK 状态：active、buffering、disabled、sampled、paused
• $session_recording_start_reason — 录制开始或未开始的原因
• $sdk_debug_recording_script_not_loaded — 录制器脚本被拦截（广告拦截器）
• $sdk_debug_replay_*_trigger_status — 触发器状态（URL、事件、关联标记）
• $replay_sample_rate — 捕获时配置的采样率

工作流

第 1 步 — 检查录制内容是否存在

如果用户提供了会话 ID，请先检查是否确实存在录制内容：

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

如果返回 found: false，且原因为 recording_not_found，则当前项目中不存在该会话的录制内容。 请继续第 2 步，诊断原因。 如果返回了录制元数据，则录制内容确实存在——问题可能出在 UI 或筛选条件，而非捕获过程。 其他任何错误（例如项目缺失或权限错误）都不能作为录制内容存在与否的证据。 请先解决该错误。

第 2 步 — 查询事件中的诊断信号

查询该会话最近的事件，以获取 SDK 诊断属性：

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

第 3 步 — 判断诊断结论

使用诊断逻辑参考解读这些信号。 结论按优先级排列：

1. 录制内容存在（$has_recording = true）— 已捕获录制内容，问题出在其他地方
2. 广告拦截（脚本）（$sdk_debug_recording_script_not_loaded = true）— 浏览器扩展阻止录制器脚本加载
3. 已禁用（$recording_status = 'disabled'）— 已在设置或 SDK 配置中关闭回放
4. 等待触发器（触发器状态为 trigger_pending，且均未匹配）— 录制受某个从未触发的触发器限制
5. 未被采样（$session_recording_start_reason = 'sampled_out'）— 被采样率排除
6. 缓冲区为空（$recording_status = 'buffering'、缓冲区长度 = 0，且没有数据被刷新）— 已初始化，但未生成快照
7. 刷新受阻（缓冲区长度随事件增加，而 flushed_size 始终为 0）— 已生成快照，但 /s/ 数据接收端点被广告拦截器或配置错误的反向代理阻止。需要查询会话各事件的变化趋势才能检测——请参阅 examples.md 中的示例 3
8. 未知 — 信号不符合任何已知模式

第 4 步 — 检查项目级设置（无会话 ID 时）

当用户询问整个项目中为何缺少录制内容（未指定具体会话）时， 请查询最近的会话以检查相关模式：

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

查找以下模式：

• 全部为 disabled → 项目设置中已关闭回放
• 全部为 sampled_out，且采样率较低 → 采样率设置过于激进
• 全部为 script_not_loaded → 可能是 CSP 或部署问题，而非仅某位用户的广告拦截器所致
• 状态混杂 → 单个会话的问题，请深入调查具体情况

步骤 5 — 提供可执行的建议

根据判定结果，推荐具体操作：

判定	建议
广告拦截	用户的浏览器扩展正在拦截 rrweb。建议尝试关闭广告拦截器，或为录制脚本使用代理／自定义域名
已禁用	检查项目的回放设置 — 录制可能已关闭。链接到 Settings > Session replay
触发条件待满足	配置的触发条件（URL 模式、事件或功能标志）从未匹配。检查触发条件配置
未被抽样选中	在项目设置中提高抽样率，或使用触发条件确保录制重要会话
缓冲区为空	页面在首次快照前已关闭。短会话或单页导航时较为常见。可考虑降低最短时长
未知	指引用户查看故障排除文档：https://posthog.com/docs/session-replay/troubleshooting

示例

请参阅真实场景诊断示例，了解不同信号组合 如何对应不同判定。使用这些示例校准你对查询结果的解读。

提示

• 如果 $lib_version 非常旧，可能不会包含某些诊断信号。 请告知用户 — 升级 SDK 可提供更完善的诊断信息。
• 如果录制因保留期限而被删除，会话仍可能有事件，但没有录制内容。 检查会话时间戳是否在项目的保留期限内。
• 如果 $has_recording 为 true，但用户找不到录制内容，请检查它是否因时长、 活动阈值或播放列表筛选条件而被过滤。

相关技能

• diagnosing-sdk-health — SDK 过时是常见根本原因，也会削弱诊断信号
• finding-sessions-to-watch — 录制功能正常后，挑选值得观看的会话
• investigating-replay — 录制内容生成后，对其进行分析