ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

PostHog Paths 指标排查实战指南:用路径图定位导航行为变化(Paths Playbook 深度解析)

PostHog Paths 指标排查实战指南:用路径图定位导航行为变化(Paths Playbook 深度解析) PostHog Paths 指标排查实战指南用路径图定位导航行为变化Paths Playbook 深度解析【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog导读本指南围绕 PostHog 产品分析模块中的 Paths路径洞察展开聚焦从 X 到 Y 的路径变了出现了新的主导路径这类形状型shape指标异常排查。读完你将掌握如何用posthog:query-paths做等长区间对比、如何用趋势查询拆解端点流量、如何分段验证路径差异、以及如何结合录制与错误追踪交叉验证结论——整套方法论来自 products/product_analytics/skills/investigate-metric/references/paths-playbook.md并由仓库源码与 Schema 定义提供底层佐证。为什么 Paths 是形状指标而不是数值指标当用户报告从 X 到 Y 的路径变了出现了不同的主导路径时先要意识到这与其他指标的差异。Paths 洞察描述的是用户在事件之间的导航流转形态变化通常体现为边edge的流量迁移而不是某个标量数字的单一移动。这一点决定了排查手段不能只盯一个聚合值要观察边source → target的进出量变化需要成对的时间区间对比才能定义变了结论往往要靠分段segment、录制recordings与错误日志交叉验证而不是无限跑查询。在仓库实现中Paths 查询的产物正是边的集合。paths_query_runner.py 的to_query()方法以last_path_key AS source_event, path_key AS target_event, COUNT(*) AS event_count的形式聚合出每条边及其事件量并按event_count DESC排序返回——这就是dominant path主导路径概念的数据来源。一、确定变了等长区间双跑对比为什么不能直接加 compareFilterPathsQuery不支持compareFilter对比过滤器。这一点在文档中明确指出也与 Schema 定义一致查看 posthog/schema.py 中的PathsQuery模型它包含dateRange、pathsFilter、properties、samplingFactor、filterTestAccounts等字段但没有compareFilter字段。同样地TrendsQuery/StickinessQuery支持compareFilter: {compare: true}而 Paths 需要自己跑两次查询。双跑示例JSON 查询体第一次查询取最近 7 天路径起点为/home、终点为/checkout只统计$pageview类型事件最多返回 50 条边posthog:query-paths { kind: PathsQuery, dateRange: { date_from: -7d }, pathsFilter: { includeEventTypes: [$pageview], startPoint: /home, endPoint: /checkout, edgeLimit: 50 } }第二次查询取等长的前一个 7 天窗口posthog:query-paths { kind: PathsQuery, dateRange: { date_from: -14d, date_to: -7d }, pathsFilter: { includeEventTypes: [$pageview], startPoint: /home, endPoint: /checkout, edgeLimit: 50 } }对比两组结果的边集合找出哪条边获得了流量、哪条边丢失了流量gain / lost volume。窗口等长是关键前提——不等长的窗口无法直接比较边权重。参数语义结合源码核实参数类型默认值语义kindstringPathsQuery必填查询类型标识dateRange.date_from/date_tostring无支持相对写法-7d与绝对日期includeEventTypesarray空含所有事件参与路径的事件类型见下方PathType枚举startPointstring无只保留从该节点开始的路径endPointstring无只保留在该节点结束的路径edgeLimitint50返回的最大边数以上默认值可在 PathsFilter 定义 中直接核实edgeLimit: int | None 50、stepLimit: int | None 5。而PathType枚举在 posthog/schema_enums.py 中定义class PathType(StrEnum): FIELD_PAGEVIEW $pageview FIELD_SCREEN $screen CUSTOM_EVENT custom_event HOGQL hogql在 paths_query_runner.py 的_get_event_query()中可以看到这四个类型的底层翻译$pageview→event $pageview路径节点取自$current_urlURL$screen→event $screen路径节点取自$screen_namecustom_event→NOT startsWith(events.event, $)即排除所有以$开头的自动捕获事件hogql→ 使用pathsHogQLExpression自定义表达式。两个补充细节源码佐证URL 尾部斜杠会被剥离。construct_event_hogql()中对$pageview应用了replaceRegexpAll(ifNull(properties.$current_url, ), (.)/$, \\1)同时_strip_trailing_slash()会对startPoint/endPoint做同样的归一化保证查询值与存储值匹配见 paths_query_runner.py。因此传入/checkout/与/checkout效果一致。边权重过滤。minEdgeWeight/maxEdgeWeight会在外层查询的HAVING子句中生效get_edge_weight_exprs()用于剔除低流量噪声边或高流量主干边edgeLimit则作为最终LIMIT见 paths_query_runner.py。底层执行链路便于深入阅读PathsQueryRunner的核心流水线是paths_events_query()筛选事件并按事件类型归一化出path_itempaths_per_person_query()按person_id用groupArray聚合路径再按会话阈值默认 30 分钟SESSION_TIME_THRESHOLD_DEFAULT_SECONDS切分会话、压缩连续重复节点compact_path并定位startPoint/endPointto_query()将每个人的路径拆成相邻边source_event → target_eventCOUNT(*)计数、avg(conversion_time)计算平均转换时长最后按event_count降序返回。其中同人会话切分由get_session_threshold_clause()实现arraySplit(x - if(x.3 1800, 0, 1), paths_tuple)即同一用户两次事件间隔超过 30 分钟即视为新会话paths_query_runner.py。理解这一点对解读结果很重要路径是会话内的导航序列跨会话跳转不会被连成一条边。二、先检查端点自身流量A → B 下降可能只是 A 或 B 下降从 A 到 B 的路径掉了最常见的假象是端点本身A 或 B的流量掉了路径图只是被动地反映这一点。此时再深的路径分析都是多余的。做法对每个端点事件单独运行posthog:query-trendsposthog:query-trends { kind: TrendsQuery, dateRange: { date_from: -14d }, interval: day, series: [ { kind: EventsNode, event: $pageview, properties: [{ key: $current_url, operator: exact, value: /home }] }, { kind: EventsNode, event: $pageview, properties: [{ key: $current_url, operator: exact, value: /checkout }] } ] }判断逻辑如果 A 或 B 自身的趋势发生了移动 → 进入该事件对应的趋势 playbooktrend-playbook.md排查而不是继续在路径上纠缠如果两端都稳定而路径边的流量在变 → 问题确实出在中间导航环节路径分析才真正有价值。这与漏斗 playbook 的思路一脉相承FunnelsQuery的步骤 2 也要求先区分是入口entries掉了还是完成completions掉了参见 funnel-playbook.md。三、确认工具选型问的是转化率就别用路径路径洞察回答的是形状shape问题用户在页面/事件之间怎么走、在哪分叉、主流路线是否漂移。它不是转化率工具。如果用户的实际问题是转化率下降了某一步流失增加了 → 正确做法是构建漏斗Funnel并转入 funnel-playbook.md。漏斗 playbook 还反过来利用路径它的步骤 5 建议用posthog:query-paths且endPoint指向失败步骤观察没能走到该端点的用户去了哪里——这正是两个洞察的互补用法。如果问题是用户从 X 到 Y 的路线怎么变了主流路径变成了什么 → 才是 Paths 的用武之地。在指标分类上这属于 investigate-metric 技能 的 Step 1——先读query.kind判断指标类型PathsQuery路由到 paths playbookFunnelsQuery路由到 funnel playbookTrendsQuery路由到 trend playbook。判断错工具整个排查方向就错了。四、分段验证路径形状是否因用户群体而异为什么不支持 breakdownFilterAssistantPathsQueryAgent 使用的路径查询变体不支持breakdownFilter。查看 schema.py 中的 AssistantPathsQuery其字段包含aggregation_group_type_index、dateRange、filterTestAccounts、pathsFilter、properties等同样没有breakdownFilter。PathsQuery/PathsFilter也没有 breakdown 能力——路径洞察本身是一条主流路径而不是多维度分桶后的多条路径。用顶层 properties 过滤 分段重跑正确的分段做法是通过查询顶层的properties字段过滤然后对每个分段重新跑一次路径查询posthog:query-paths { kind: PathsQuery, dateRange: { date_from: -7d }, properties: [ { key: $geoip_country_code, operator: exact, value: US, type: person } ], pathsFilter: { includeEventTypes: [$pageview], startPoint: /home, endPoint: /checkout, edgeLimit: 50 } }properties在 Schema 中被定义为list[AnyPropertyFilterDiscriminated] | PropertyGroupFilter | Noneschema.py支持事件属性、Person 属性、分组属性等过滤维度并在 paths_query_runner.py 中通过property_to_expr()翻译成 SQL 的WHERE条件注意这是顶层过滤作用在整个查询上等价于对每个 segment 重跑。何时该做分段当路径形状在不同浏览器 / 国家 / 套餐plan之间出现剧烈差异时这本身就是变化是分段特定segment-specific的有力证据——例如某个国家因为落地页改版走了完全不同的路线而整体主流路径没变。文档还提示了另一条更轻的路径先跑一次全量查询如果发现主流边变了再针对可疑分段如某个$browser或app_version重跑验证而不是一开始就对每个维度穷举。分段维度的优先序参考shared-patterns.md 给出了候选维度的大致信号强度排序可直接套用$feature/flag_key—— 功能开关发布后信号最强$browser、$os、$device_type、$geoip_country_code—— 平台 / 地区问题app_version、$lib_version—— SDK 回归is_identified、$is_first_session、plan / tier —— 用户状态问题自定义事件属性 —— 通常最有诊断性。五、录制 错误追踪让证据闭环录制比继续跑查询更快当发现新的主导边出现例如用户开始大量从/home→/pricing→/signupPull 这段路径上用户的会话录制session recordings往往比继续跑查询更快暴露 UI 变化用posthog:query-session-recordings-list拉取符合受影响分段的录制列表用posthog:session-recording-get获取单条录制详情。这与 shared-patterns.md 中Session recordings一节的建议一致对于 UI 形态导致的下降看三到四条录制通常比跑更多查询快。例如某次改版后按钮位置变了、某个步骤加了新表单用户的行为路径会立即在录制中显现。错误追踪交叉验证分叉点在用户开始分叉diverge的页面上用posthog:query-error-tracking-issues-list检查是否存在错误。但要警惕错误只是候选不是结论。按 shared-patterns 中的三条确认标准验证时序Timing错误量是否与指标变动对齐机制合理Plausible mechanism错误是否真的影响该指标表面例如提交接口的 500 可以导致用户放弃该步骤而控制台 warning 通常不能用户重叠User overlap报错的用户是否与走新路径/流失的用户重叠。任一条不满足都应把错误标记为巧合并继续排查。找到根因后的收尾动作按 investigate-metric SKILL.md 的 Step 5调查结论应写入标准格式Anomaly / Likely cause / Confidence / Evidence / Possible causes ruled out / Affected segment / Data gaps / Suggested follow-ups并主动提供posthog:insight-create—— 保存关键图表posthog:annotation-create—— 在根因时间点打标注供后续对比引用。六、常见坑与速查场景正确做法A→B 路径掉了先查 A、B 端点自身趋势第 2 节再进路径排查转化率下降了路径是错的工具改用漏斗 playbook第 3 节某个分段的路径形状不同用顶层properties过滤后逐段重跑第 4 节新的主导边出现了拉录制看 UI、查错误追踪交叉验证第 5 节需要比较两个周期等长窗口双跑对比边 gain/lost第 1 节URL 带尾部斜杠匹配不上无需处理服务端自动归一化见_strip_trailing_slash相关文档导航主技能与整体流程investigate-metric/SKILL.md含 Step 1 指标分类 → Step 5 结论格式本 playbook 原文paths-playbook.md配套 playbookfunnel-playbook.md、trend-playbook.md通用配方shared-patterns.md分段维度、录制、错误/日志交叉验证源码实现paths_query_runner.py查询流水线、schema.pyPathsQuery/PathsFilter/AssistantPathsQuery定义、schema_enums.pyPathType枚举测试用例test_paths_query_runner.py可对照学习各参数的实际行为【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表