analyzing-experiment-session-replays

分析实验会话回放

此技能将指导你分析实验变体的会话录制，以了解对照组和测试组之间的行为差异。

何时使用此技能

在以下情况下使用此技能：

• 用户要求分析实验的会话回放
• 用户想了解用户在不同实验变体中的行为差异
• 用户要求比较用户在对照变体和测试变体中的行为
• 用户想获得定性见解，以补充实验指标
• 用户提出类似“用户在我的实验中有什么行为？”或“显示变体 X 的会话回放”的问题

前提条件

分析会话回放之前：

1. 实验必须已启动（不能处于草稿状态）
2. 项目必须已启用会话回放
3. 用户必须已接触过实验变体
4. 实验必须有开始日期

工作流

1. 获取实验详情和功能标志变体

首先，获取实验信息和功能标志变体（权威来源）。

步骤 1a：获取实验元数据

你可以选择以下任一方式：

• 选项 A：如果你已从上下文中获得实验 ID，则使用 experiment-get 工具
• 选项 B：通过 HogQL 查询 experiments 表：

SELECT
    e.id,
    e.name,
    f.key AS feature_flag_key,
    e.start_date,
    e.end_date
FROM system.experiments e
JOIN system.feature_flags f ON f.id = e.feature_flag_id
WHERE e.id = <experiment_id>

从实验数据中提取：

• feature_flag_key：用于控制实验的功能标志
• start_date 和 end_date：实验的时间范围

步骤 1b：从功能标志获取变体

重要：始终从功能标志获取变体，不要从 experiment.parameters.feature_flag_variants 获取。 参数可能不同步或已弃用。功能标志才是权威来源。

查询功能标志以获取当前变体：

SELECT filters.multivariate.variants AS variants
FROM system.feature_flags
WHERE key = '<feature_flag_key>'

直接选择 variants 路径——对于具有大型定向配置的标志，选择整个 filters 对象会导致结果被截断。 结构示例：[{"key": "control", "name": "Control", "rollout_percentage": 50}, {"key": "test", ...}]

变体的 key 值（例如 "control"、"test"、"variant_a"）将用于筛选会话录制。

2. 为每个变体构建会话录制筛选条件

为实验中的每个变体构建录制筛选条件，以匹配接触过该变体的用户。

变体的筛选条件结构（输入到 query-session-recordings-list）：

{
  "date_from": "<experiment.start_date>",
  "date_to": "<experiment.end_date or current time>",
  "filter_test_accounts": true,
  "properties": [
    {
      "type": "event",
      "key": "$feature/<feature_flag_key>",
      "operator": "exact",
      "value": ["<variant_key>"]
    }
  ]
}

要点：

• $feature/<flag_key> 事件属性会记录每个事件上的标志值——按其筛选可以匹配该变体处于启用状态时的录制。这是对曝光情况的近似，覆盖范围比实验的曝光事件更广（$feature_flag_called，或新发布流程中的 $experiment_exposure；二者都会按身份去重）：适合浏览不同变体下的行为，但并非分析人群的精确映射——需要精确筛选条件时，scanning-experiments-with-replay-vision 技能会推导出该条件
• value 是变体键字符串数组（例如 ["control"]）；对于布尔标志，使用 ["true"] 或 ["false"]
• 避免使用 type: "flag" / flag_evaluates_to 属性筛选条件来限定变体——录制查询虽然接受该条件，却会悄悄忽略它，返回未筛选的结果（最后验证于 2026-06-10）。如果仍想尝试，务必先验证它确实会筛选：使用不存在的标志键进行查询时，应返回零条录制
• 将日期范围设置为实验的开始和结束日期
• 设置 filter_test_accounts: true，以排除测试用户

3. 获取每个变体的录制

使用第 2 步构建的筛选条件，调用 query-session-recordings-list 工具。

每个变体调用一次工具，以获取各组的录制：

• 变体 "control" → control 组的录制
• 变体 "test" → test 变体的录制
• 如果实验的变体多于 2 个，还需处理其他变体

该工具会返回录制列表及其元数据，包括：

• distinct_id — 用户的唯一 ID
• recording_duration、active_seconds、inactive_seconds
• click_count、keypress_count、mouse_activity_count
• console_log_count、console_warn_count、console_error_count
• start_url — 访问的第一个页面 URL
• start_time / end_time、activity_score

4. 比较和分析

通过查找以下内容来比较各变体的录制：

定量模式：

• 会话时长差异
• 活跃度（点击、按键）
• 控制台错误率
• 跳出率

定性见解：

• 用户困惑或沮丧的迹象
• 不同的导航路径
• 功能发现模式
• 错误恢复行为

5. 展示发现

总结各变体间的行为差异，重点说明：

• 每个变体的录制总数
• 各变体独有的显著行为模式
• 观察到的可用性问题或阻碍点
• 基于定性数据提出的建议

6. 观察能展现行为；提问能了解用户对行为的看法

观看会话和询问用户是两种不同的研究方式，不能互相替代。录制能展现用户对改动的实际操作；在用户完成实验流程时展示一份简短问卷，则能了解他们对改动的看法——包括评分和可选评论，并可按变体查看。对于改动幅度较大的面向用户的功能，两者结合能比单独使用任何一种方式获得更完整的定性认识。因此，当第 4 步的行为比较无法反映用户看法时，或当录制中出现值得向相关用户求证的模式时，可提及这一选项。每次对话最多提一次；如果用户拒绝，就不再提。

默认向所有接触到改动的用户提问，而不是只面向一个变体：只向一组展示弹出窗口本身就会造成组间差异，而且响应事件会携带变体信息，因此仍可区分不同组。

→ 参见 [[diagnosing-experiment-health]] 中的 references/qualitative-feedback.md

示例交互

User: "How are users behaving in my checkout experiment?"
Agent steps:
1. Query experiment details (ID: 123, feature_flag_key: "checkout-flow-test", date range: 2025-01-01 to 2025-01-31)
2. Query feature flag "checkout-flow-test" to get variants from filters.multivariate.variants
3. Extract variant keys: "control" and "new-checkout"
4. Build filters for control variant:
   - Property filter: { type: "event", key: "$feature/checkout-flow-test", operator: "exact", value: ["control"] }
   - Date range: 2025-01-01 to 2025-01-31
5. Call query-session-recordings-list with control filters → 147 recordings found
6. Build filters for new-checkout variant and call query-session-recordings-list → 152 recordings found
7. Compare patterns:
   - Control: Average 3m 45s session duration, 12% console errors
   - New-checkout: Average 2m 30s session duration, 5% console errors
8. Present findings:
   "I analyzed session replays for your checkout experiment. The new checkout flow shows:
   - 33% faster completion (2m 30s vs 3m 45s)
   - 58% fewer console errors (5% vs 12%)
   - Users in the new variant navigate directly to payment, while control users often backtrack to review cart
   - Recommendation: The new checkout flow reduces friction and errors"

重要说明

不要臆测：

• 分析前务必确认实验有录制
• 检查实验是否已启动（是否有 start_date）
• 如果没有找到录制，请明确告知用户

筛选条件构建：

• $feature/<flag_key> 事件属性用于将录制限定到某个变体
• 每个变体使用一个筛选条件——每个变体调用一次工具，并使用各自的筛选条件
• 对于布尔标记，请使用 ["true"]/["false"] 作为值，而不是变体键

错误处理：

• 如果实验处于草稿状态，请告知用户实验尚未开始
• 如果没有录制，建议启用会话回放或等待用户流量
• 如果变体数量与预期不符，请再次检查实验配置

相关工具

• query-session-recordings-list：使用筛选条件检索会话录制的核心工具
• experiment-get：获取实验元数据；使用 experiment-results-get 获取统计结果
• execute-sql：通过 HogQL 查询 experiments 表以获取详细信息

相关技能

• diagnosing-experiment-health — 定量分析：检查同一实验中的偏差和统计显著性
• investigating-replay — 深入分析任一变体中的单个会话
• finding-sessions-to-watch — 在实验场景之外筛选要观看的会话