什么时候翻这页:接手一个用 PostHog 的产品、要盘点它埋了什么 / 要建数据看板 / 想让 agent 用嘴查数。含官方文档要点 + 一条原创的登录态直查 SOP(第七节,文档里没有,盘点别人建的项目时最省事)。
一、PostHog 是什么
开源的一体化产品数据平台("Product OS"),可理解为"自己可控、能写 SQL 深查的 GA + 神策"。主打产品分析(Product Analytics),同时带网站分析、会话回放(Session Replay)、功能开关(Feature Flags)、A/B 实验(Experiments)、问卷(Surveys)、错误跟踪、LLM Analytics 等一堆子产品。Cloud 分美国区(us.posthog.com)和欧洲区(eu.posthog.com)。
两个端点别混:事件上报走 us.i.posthog.com(公开,前端 SDK 用,无需鉴权);后台/私有 API 走 us.posthog.com(需鉴权)。踩过一次就记住——想用 API 查数据却打到 i. 端点会一直 401。
二、核心概念(会这几个词就能看懂后台)
| 概念 | 大白话 | 关键备注 |
|---|---|---|
| Event 事件 | 用户一次动作,数据最小单位 | 四要素:事件名 / distinct_id / 时间戳 / properties;$ 前缀属性是 PostHog 内置(如 $host、$browser) |
| Property 属性 | 挂在事件上的附加信息 | 如付费事件挂 price_usd |
| distinct_id | 区分"这是谁"的唯一标识 | 匿名是随机 UUID,登录后应换成用户 ID |
| Person 用户档案 | 同一人所有事件归拢的档案 | 只有 identified 事件才建档案 |
| identify | 把匿名访客和登录用户接起来 | 登录/注册后尽快调 posthog.identify(唯一ID,{...})。大坑:两个人共用一个 distinct_id(如误传 null/true)会被合并成一个人 |
| Insight 图表 | 一张分析图,7 种类型 | 见第三节 |
| Dashboard 看板 | 多张 Insight 拼一屏 | 可生成公开分享链接,公开看板每 30 分钟刷新 |
| Action | 把几个事件打包当一个用 | 有追溯性(对历史事件也生效),可给单事件"重命名"、合并新旧口径 |
| Cohort 人群 | 按条件圈的一群人 | Static 固定名单 / Dynamic 每 24h 自动更新 |
| HogQL / SQL | 图表满足不了就写 SQL | ClickHouse SQL 的包装,properties.$xxx 语法访问属性 |
| Autocapture | 自动采集,不写代码就有 | 页面浏览/点击自动记($ 开头);量大、语义泛化("点了写着删除的按钮") |
| 手动埋点 | 研发写代码显式上报的业务事件 | 语义明确(如 payment_success);官方建议二者混用 |
三、Insight 7 类 + 四个高频入口
7 种图表:Trends(指标随时间)/ Funnels(步骤转化率)/ Retention(留存)/ User Paths(浏览路径)/ Stickiness(使用粘性)/ Lifecycle(把用户分成新增-回流-流失-沉睡四态看健康度)/ SQL(自定义查询表格)。
四个高频入口:
- Activity — 实时原始事件流,验证"埋点到底报没报上来"就看这。
- Product analytics → New — 新建图表。
- Dashboards — 拼看板。
- SQL — 写 HogQL 深查。
四、关键口径坑(文档里散落,踩过才知道)
- Total count vs Unique users:Trends 每条线单独选聚合方式。按天粒度的 Unique users = DAU。
- WAU/MAU 是"滚动窗口":指"过去 7/30 天有事件的独立用户",逐日滚动,不是自然周/自然月——和很多 BI 工具口径不同,对外报数必须注明,否则被质疑对不上。
- Count per user:人均事件次数,可取平均/中位/P90——看"人均聊天轮次""人均下单数"直接用它,不用写 SQL。
- First-time 过滤:只统计用户第一次发生某事件,做新增/激活分析用;有两种模式(first-ever occurrence / first matching event),含义不同别选错。
- Breakdown 分桶(bins):数值属性 breakdown 可设 bins,直接出直方图;Trends 最多 3 个 breakdown,默认只显示前 25 个值(要点"Load more")。
- 统计新/回访用户的惯用法:埋点用
$set_once写一个不可覆盖的注册日期属性,或用 Cohort "completed event for the first time",或直接用 Lifecycle 图自动拆。
五、MCP 接入(让 agent 用嘴查数)
- 官方托管 server:
https://mcp.posthog.com/mcp(按账号自动路由 US/EU,不用自部署)。 - Claude Code 一条命令:
claude mcp add --transport http posthog https://mcp.posthog.com/mcp -s user,重启后首次使用弹浏览器 OAuth 授权(用已有 PostHog 账号登录即可,不用手动建 key)。 - 只读模式:URL 加
?readonly=true,所有建/改/删工具被剔除——PM 日常查数用这个,零误操作;要建看板再换全权限。 - 能力:查/建/改 Insight 和 Dashboard、execute-sql、read-data-schema(查事件属性定义)、Feature Flags、实验、搜文档等(官方称 450+ 工具,名字随版本迭代,别写死)。
- 备选鉴权:Settings → Personal API keys,官方 MCP 预设直达
app.posthog.com/settings/user-api-keys?preset=mcp_server,key 前缀phx_,只显示一次。 - 费用:MCP 本身免费,底层查询按正常账单计。
六、计费(够用判断)
每月 100 万 events 免费(免费版 1 个项目、数据留 1 年)。超量匿名事件约 $0.00005/条起、量越大越便宜;identified(调过 identify 的实名)事件约贵 5 倍($0.000248/条起)——这是主要成本杠杆,autocapture 全开会推高事件量。可设 billing limit 按产品封顶防意外账单。判断口径:百万事件/月内都是免费,不用担心多埋几个业务事件爆费用。
七、⭐ 实查 SOP(原创,文档没有,复用价值最高)
要盘点一个别人建的 PostHog 项目里到底有什么,别在 UI 一页页点。最快路径:
- 进后台:沙盒 Chrome 用 Google/GitHub SSO 登进 us.posthog.com,拿到登录态 cookie。
- 页面内 fetch 内部 API(
fetch(url,{credentials:'include'})):- 事件定义:
GET /api/projects/<id>/event_definitions/?limit=250 - 看板:
GET /api/projects/<id>/dashboards/;图表:.../insights/?saved=true - 项目信息/token:
GET /api/projects/<id>/
- 事件定义:
- 跑 HogQL 深查(最有用):
POST /api/environments/<id>/query/,body{"query":{"kind":"HogQLQuery","query":"<SQL>"}},header 必带X-Csrftoken(值从document.cookie里posthog_csrftoken取,漏了会 403)。 - 必查的三条 HogQL(判断数据健康度,比看图快):
- 各事件量级+独立用户+首末时间:
SELECT event, count(), count(DISTINCT person_id), toDate(min(timestamp)), toDate(max(timestamp)) FROM events WHERE timestamp > now() - INTERVAL 90 DAY GROUP BY event ORDER BY 2 DESC - 按域名看数据来源(抓"生产是否断流"的关键):
SELECT properties.$host, count(), toDate(max(timestamp)) FROM events WHERE timestamp > now()-INTERVAL 90 DAY GROUP BY 1 ORDER BY 2 DESC—— 一眼看出真实数据来自生产站还是 staging/localhost/内部后台。 - 按 environment 属性看测试/生产混池:
SELECT properties.environment, count() FROM events GROUP BY 1
- 各事件量级+独立用户+首末时间:
- ⚠️ 头号教训(2026-07-05 亲身翻车):先确认你查的是不是生产项目。别人给你一个 project URL,不代表它就是生产。真实事故:CompanionAI 的 PostHog 下有两个同名 "Default project"——给我的 318867 是 staging(environment 分布只有 null/development/staging、无 production 值),真生产在另一个独立项目 387337(我一开始还没权限、看不到)。我照着 318867 查,把它里生产域名的零星测试数据"4-18 之后没了"误读成生产断流,还反过来当"缺 PostHog key"的证据,给研发发了个完全错误的 P0 需求,被一句话打脸(生产 387337 近 90 天 4.6 万条、当天还在进)。开查前的 step 0 三连:①这个项目
environment分布有没有production值?没有 = 你多半在 staging;②org / 账号里是不是有多个、甚至同名的项目?/api/organizations/@current/projects/拉全;③目标生产域名的数据活到"今天"吗?三条任一异常,先怀疑"我连错项目了",而不是"生产坏了"。 - 第二教训:纯看文档 + 看板会误判,所以实查优先——但实查错对象比不实查更危险,因为你会带着"我可是亲手查的数据"的自信,把一切异常都往"东西坏了"编织(确认偏误),而不是往"我看错对象了"想。实查的前提是先用 step 0 锁定正确对象。和调研纪律"静态资料答不了'现在还在不在跑'"同源,但多一层:先确认"我查的是不是那个该跑的东西"。
八、AI 聊天产品的"轮次分布"做法
- 快版:Trends,事件 = 消息事件,聚合选 Count per user 取中位/P90——"典型用户每天聊几轮"。
- 直方图版:SQL Insight 两层聚合(内层按 session_id 数消息数,外层按轮次分桶数会话):
SELECT multiIf(turns<=5,'1-5',turns<=10,'6-10',turns<=20,'11-20','20+') AS bucket, count() AS sessions FROM (SELECT properties.chat_session_id AS sid, count() AS turns FROM events WHERE event='<消息事件>' GROUP BY sid) GROUP BY bucket ORDER BY bucket - AI 专用:PostHog 有 LLM Analytics 产品线,把每次模型调用记为标准事件(
$ai_generation),自带 per-user 成本/轮次看板,做 AI chat 产品值得评估——轮次分布可直接建在这类事件上,不必单独埋。
信源
官方文档(一手):posthog.com/docs 及 /data/events、/data/persons、/product-analytics/identify、/product-analytics/insights、/product-analytics/trends(aggregations/filters/breakdowns)、/funnels、/data/actions、/data/cohorts、/sql、/product-analytics/autocapture、/model-context-protocol(及 claude-code/tools/faq 子页)、/api/personal-api-keys、/pricing、/ai-observability/start-here。实查 SOP 为 2026-07-05 CompanionAI 看板调研中实操验证得出。