埋点事件模型选型：扁平宽表 vs 事件溯源，一次把 event 该长什么样讲清楚

作者许望舒

埋点事件模型指标体系数据治理数据分析

一、现象与背景

接手一个 B 端 SaaS 的数据团队，日均埋点量约 1.8 亿条事件，覆盖 12 条产品线。接手第一周就撞上一堵墙：同一个「加购」行为，三个业务方给出的数字分别是 3.2 万、4.1 万、2.7 万——差了将近 50%。

查下来数据本身没错，错在三个团队各自埋了点：event 名一个叫 add_cart、一个叫 cart_add、一个叫 add_to_cart；商品字段一个叫 sku_id、一个叫 item_id。

问题不在某一行脏数据，而在「事件长什么样」这件事从来没有被当成一份契约来管。埋点模型没定死，后面所有指标口径都跟着漂。

二、原理 / 根因分析

埋点数据是先写后读的：写的时候（SDK 上报）成本极低，读的时候（取数、建指标、出报表）成本极高。一个 1.8 亿/天的事件流，每多一个口径分歧，就要在 BI 里多维护一段几乎一样的 SQL。

根因是事件模型（event model）没被当成 API 契约来治理，它更像每个业务方随手起的变量名。两种主流建模路线的取舍，本质是「写时复杂度 vs 读时复杂度」的分配：

扁平宽表（flat / wide）：每个业务事件一个独立 event，字段拍平在顶层。读的时候 WHERE event='add_to_cart' AND item.id=? 一步到位，BI 友好；缺点是事件一多就字段爆炸、schema 漂移，同一语义在不同事件里字段名不一致。
实体 + 属性（entity / nested）：核心实体（user、item、session）抽成结构化子对象，事件只描述「谁对谁做了什么」。读时要展开嵌套（JSON 提取），但语义统一、扩展性好。

三、具体做法

我最终选了**「强约束的扁平 + 核心实体白名单」**的混合方案，落地成一份可校验的 event schema：

{
  "event": "item.add_to_cart",
  "ts": 1718000000000,
  "v": 2,
  "user": { "uid": "u_88231", "plan": "pro" },
  "item": { "id": "sku_4091", "cat": "server" },
  "ctx":  { "src": "search", "ab": "exp_214" }
}

四条硬约定：

event 用点分命名空间 {domain}.{action}，禁止 add_cart 这种裸名；
核心实体（user / item / session / order）走白名单子对象，字段名全局唯一；
其余业务字段进 ctx，允许自由但必须带 domain 前缀；
顶层固定字段（event / ts / v / uid）由 SDK 统一注入，业务方不允许自己填。

校验用 JSON Schema 卡在上报网关：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": ["event", "ts", "v"],
  "properties": {
    "event": { "pattern": "^[a-z_]+\\.[a-z_]+$" },
    "v":     { "const": 2 }
  }
}

取「加购率」的 SQL 对比（就是当初三个口径打架的那个指标）：

-- 治理前：三个 event 名都要 OR 进来
SELECT date_trunc('day', ts) AS d,
       COUNT(DISTINCT uid) / COUNT(DISTINCT item.id) AS add_rate
FROM   events
WHERE  event IN ('add_cart','cart_add','add_to_cart')
  AND  item.id IS NOT NULL
GROUP  BY d;

-- 治理后：单一命名空间，口径只有一份
SELECT date_trunc('day', ts) AS d,
       COUNT(DISTINCT user.uid) / COUNT(DISTINCT item.id) AS add_rate
FROM   events
WHERE  event = 'item.add_to_cart'
GROUP  BY d;

治理后我们做了 30 天回放，item.add_to_cart 单一口径覆盖了原来三分支 98.6% 的量，剩下 1.4% 是历史脏数据（旧 SDK 未升级）。

四、踩过的坑 / 反直觉之处

别追求「一个 event 管所有」。最早有人提过把所有行为塞进 event='action' + action_type 字段，结果 BI 写报表时几乎每行都要 CASE WHEN action_type，可读性比三个 event 还差。扁平化是为「读」服务的，不是为「少起 event 名」服务的。
v 版本号比想象中重要。第一次升级 schema 时忘了加 v，导致新老数据混在一个流里，item.id 和旧 item_id 并存了 6 周，下游 11 张报表全部要兼容两套字段。加上 v 后，取数逻辑可以按版本路由，脏数据窗口从「永久」缩到「可枚举」。
网关校验会误伤，但值得。JSON Schema 上线头两天拦下了 4.2% 的异常上报，其中 3.1% 是客户端把 uid 传成了手机号（脱敏后为 [已脱敏]）。这类脏数据一旦进数仓，清理成本约是拦截成本的 20 倍。
点分命名会被下游当层级解析。有个 BI 工具默认按 . 拆 event 名做目录树，把 item.add_to_cart 拆成了两级菜单，反而比扁平更乱。命名约定必须和消费端工具的能力对齐。

五、结论与可复用清单

埋点模型不是一次性的技术选型，而是一份长期维护的契约——它的成本不在「写对」，而在「读的时候不用猜」。

可复用清单：

[ ] event 强制 {domain}.{action} 点分命名，SDK 层校验，裸名直接拒收；
[ ] 核心实体（user / item / session / order）抽成白名单子对象，字段名全局唯一；
[ ] 顶层固定字段由 SDK 注入，业务方禁止自定义；
[ ] 每个 event 带 v 版本号，schema 变更走版本路由而非原地改字段；
[ ] 上报网关挂 JSON Schema 校验，拦截脏数据；
[ ] 每个「核心指标」在指标字典里登记唯一 event + 唯一过滤条件，禁止多口径并存；
[ ] schema 变更走 PR + code review，把它当 API 变更管理，而不是「改个字段名」。

一句话：先把 event 长什么样定成契约，再去谈指标口径；顺序反了，就是三个团队三个数字。

赞 2 · 收藏 0 · 评论 0 · 浏览 0

暂无评论。