2. 埋点分类与作用域：业务埋点、技术埋点、用户行为埋点的边界归属
埋点一旦脱离“分类”与“作用域”的约束，就会沦为数据沼泽——业务需求、运维监控、体验分析混杂在同一管道中，导致字段膨胀、权限混乱、治理成本飙升。本章从模块边界出发，明确三类埋点的归属、传递路径与职责边界，为后续状态同步与信任链路打下分类基座。
2.1 三类埋点的定义与归属
| 类别 | 定义 | 典型事件 | 归属模块 | 产生时机 |
|---|---|---|---|---|
| 业务埋点 | 反映业务核心指标、转化漏斗、收入统计的事件 | 下单、支付、注册、退款 | 业务服务层（订单、支付、用户） | 业务逻辑触发时 |
| 技术埋点 | 反映系统性能、错误率、资源消耗的监控事件 | 接口响应超时、OOM、CPU 高水位 | 基础设施 / 中间件层（APM、日志） | 系统运行时自动采集 |
| 用户行为埋点 | 反映用户与界面交互的事件，无业务语义 | 点击、滑动、停留、页面曝光 | UI / 交互层（前端 SDK） | 用户操作触发 |
边界划分原则： 谁产生，谁负责。业务埋点由业务模块定义字段；技术埋点由运维框架标准化；用户行为埋点由前端 SDK 统一封装。禁止跨模块定义埋点字段，避免耦合。
2.2 埋点传递路径与作用域层级
三类埋点从不同层级的模块产生后，经汇聚、清洗、路由，最终到达数据湖或实时计算层。传递路径的每一跳都对应明确的模块边界和信任策略。
核心约束： 用户行为埋点不得直接写入业务库；技术埋点不得携带用户身份标识；业务埋点必须包含
trace_id 用于关联三者。
下图展示了三类埋点的产生源、汇聚节点与最终流向：
2.3 状态同步策略：全量 vs 增量
不同埋点作用域要求的状态同步策略截然不同：
| 参数 | 用户行为埋点 | 业务埋点 | 技术埋点 |
|---|---|---|---|
| 同步模式 | 实时（秒级） | 准实时（分钟级）或离线 | 实时（秒级） |
| 数据量级 | 极高（十万级/秒） | 中等（千级/秒） | 高（万级/秒） |
| 全量/增量 | 增量为主，全量兜底 | 全量+增量双模 | 增量+累积 |
| 冲突处理 | 丢弃重复（去重键：session_id+timestamp） | 业务幂等（order_id 唯一） | 覆盖最新（时间戳最大优先） |
常见风险： 用户行为埋点若使用全量同步，会导致管道拥堵；技术埋点若使用业务幂等规则，会丢失系统瞬时峰值数据。必须为每种埋点配置独立的同步策略。
2.4 组件职责与信任链路
| 组件 | 职责 | 信任策略 |
|---|---|---|
| 埋点 SDK | 封装采集逻辑，本地缓存，采样控制 | 客户端签名（app_id + secret） |
| 传输层（Agent） | 批量压缩，断点续传，路由分发 | 服务端验签，IP 白名单 |
| 清洗层 | 格式校验，字段补全，去重 | 字段白名单，禁止动态注入 |
| 存储层 | 分区存储，TTL 管理，数据回溯 | 行级权限，脱敏规则 |
| 治理层 | 埋点目录管理，字段版本，废弃通知 | 变更审批链，Schema Registry |
2.5 数据流 / 控制流 / 信任链路
- 数据流： 埋点数据从产生端经汇聚、管道流向消费端，作用域内的模块只读写自己负责的字段。
- 控制流： 采样率、开关、黑名单由治理层下推至 SDK / Agent，控制流与数据流分离，避免数据流被控制指令阻塞。
- 信任链路： 每跳都需要验签、鉴权、防重放。业务埋点包含
trace_id，技术埋点包含host_id，用户行为埋点包含session_id，三者通过global_trace_id关联。
2.6 选型权衡
| 权衡点 | 推荐方案 | 反模式 |
|---|---|---|
| 客户端 vs 服务端埋点 | 用户行为用客户端SDK；业务埋点用服务端切面 | 客户端直接写业务数据库 |
| 实时 vs 离线 | 用户行为/技术埋点实时；业务埋点可离线 | 全量实时导致存储成本爆炸 |
| 标准化 vs 灵活性 | 通用字段统一治理，扩展字段按模块隔离 | 所有模块共用同一 schema |
2.7 落地步骤
- 定义埋点规范： 明确三类埋点的必传字段、命名规则、值域。
- SDK/Agent 集成： 按模块边界接入对应 SDK，配置采样率与签名。
- 链路测试： 在沙箱环境验证数据流、控制流、信任链路全闭环。
- 灰度上线： 按 5% → 20% → 100% 逐步放开，监控埋点丢失率。
- 监控告警： 针对三类埋点分别设置时效性（P99 < 10s）、完整性（丢失率 < 0.1%）、正确性（字段合法率 > 99.9%）告警。
2.8 验收标准
| 维度 | 验收指标 | 检查方式 |
|---|---|---|
| 分类完整性 | SDK 上报数据中 event_type 字段明确区分三类埋点 | 抽样抓包验证 |
| 边界隔离 | 业务埋点不出现前端 SDK 上报的字段；技术埋点不含用户 ID | 字段合规扫描 |
| 传递及时性 | 用户行为埋点 5s 内到达 Kafka；技术埋点 10s 内；业务埋点 30s 内 | 端到端延迟监控 |
| 信任链路 | 每条埋点都携带签名且验签通过率 ≥ 99.99% | 日志审计 |
检查清单：
- 是否已为每类埋点分配唯一的作用域标识？
- 用户行为埋点是否禁止调用业务服务 RPC？
- 技术埋点是否禁止携带 PII（个人身份信息）？
- 是否已经为三类埋点配置了独立的告警规则？