一文了解字节跳动“埋点验证平台”

埋点数据作为推荐、搜索、产品优化的基石，其数据质量的重要性不言而喻，而要保障埋点数据的质量，埋点验证则首当其冲。工欲善其事必先利其器，要做好埋点验证会面临很多技术挑战：易用性、准确性、实时性、稳定性、扩展性，如何攻克这些挑战呢，其实还是技术，这也是本文的主旨所在。

目前埋点验证已在字节内部得到广泛使用，通过一键扫码开启验证、实时上报验证、自动生成验证报告，解决了埋点数据验证难、埋点质量保障难的问题。

埋点验证流程

• 埋点生命周期：4+6
• • 4 个角色：PM、DA、RD、QA
  • 6 个节点：提出需求、设计埋点、开发埋点、测试埋点、上报埋点、分析埋点
• 埋点验证流程：3+3+3
• • 3 个角色：DA、RD、QA
  • 3 个节点：设计埋点、测试埋点、验收埋点
  • 3 个物料：埋点验证方案、埋点验证工具、埋点验证报告

先简单介绍一下产品，以便大家能对平台有整体认识，方便大家更加轻松地理解技术，平台主要包括三部分：埋点验证方案、埋点验证工具、埋点验证报告，三者相辅相成，极大的降低了用户的埋点验证成本。

• 附埋点验证工具图

技术架构图

埋点验证的链路很长，可以简单概括为三个环节：埋点上报、埋点接收、埋点验证，每个环节都有一定的复杂性，此处先介绍整体流程，让大家可以快速对全流程有所认识。其次将主要聚焦于“埋点验证”环节，此环节的重中之重是埋点验证引擎，它包括 4 个部分：规则生成器、规则选择器、埋点验证器和埋点推送器，通过对埋点验证引擎的详解让大家对“埋点如何验证”有更深的理解。

• 埋点上报环节重点是丰富的 SDK(客户端、服务端、JS、Chrome 插件)，要做到简单易用并且保证埋点实时上报。
• 埋点接收环节重点是数据接收服务(客户端-applog、Web 端-mcs、服务端-databus)、数据保存服务(消息队列)，要保证服务稳定并且保证埋点不丢失。
• 埋点验证环节重点是埋点验证引擎，要确保服务高性能并且保证埋点验证结果的准确性。

规则生成器

规则生成器将“埋点验证方案”转换为“验证规则”。埋点验证方案是验证规则的逻辑视图，方便用户操作，降低验证规则的编写和维护成本。通过逻辑视图和物理视图两层逻辑，确保了埋点验证引擎底层不受业务变化的影响。

埋点方案

埋点验证方案支持 2 种：

• 按需求验证：即新建需求计划，针对某次需求验证、
• 按元数据验证：即按元数据验证，元数据是指所有需求的并集

按元数据验证：

• 埋点名称：video_play
• • (名称、类型、是否必填、值校验、是否是场景条件)
  • enter_from,string,必传,固定值(login),是
  • duration,integer,必传,值无限制,否
  • type,integer,必传,枚举(1,2,3),否

埋点数据：

{
    "app_id":100,
    "event":"click",
    "params":{
        "enter_from":"login",
        "duration":1,
        "type":3
    }
}
复制代码

埋点规则

{
    "app_id":100,
    "event_name":"video_play",
    "logical_filter":{
        "enter_from":"login"
    },
    "meta":{
        "required_field":[
            "duration",
            "enter_from",
            "type"
        ],
        "scene":{
            "condition":"enter_from=login",
            "name":"登录页"
        },
        "validate_field":[
            "duration",
            "enter_from",
            "type"
        ]
    },
    "physical_validation":"{"$schema":"https://json-schema.org/draft/2019-09/schema","type":"object","properties":{"params":{"type":"object","properties":{"duration":{"type":"integer"},"enter_from":{"type":"string","enum":["login"]},"type":{"type":"integer","enum":[1,2,3]}},"required":["duration","enter_from","type"]}},"required":["params"]}",
    "source":"schema_scene"
}
复制代码

埋点规则字段说明

• app_id：应用 id
• event_name：埋点名称
• logical_filter：用于“规则选择器”
• physical_validation：用于“埋点验证器”
• source：区分规则来源：按需求验证、按元数据验证

规则选择器

规则选择器将依据“埋点”中的关键信息，从“验证规则池”中选择出对应的“埋点验证规则”。

• 选择逻辑：具体数据参考“规则生成器”
• • 根据“埋点数据”中 app_id 和 event 从“验证规则池”中筛选出“匹配的规则”
  • 将“埋点数据”的 parms 字段和“匹配的规则”的 login_filter 规字段进行匹配，选择出最终的“埋点验证规则”

埋点验证器

埋点验证器将依据“基础验证规则”以及“规则选择器”产出的“埋点验证规则”，对“埋点数据”进行验证并产出“验证结果”。

• 基础验证规则：埋点是否登记；埋点是否禁用；是否是 debug 埋点；
• 埋点验证规则：参数是否丢失；参数类型是否正确；参数取值是否符合预期:枚举、范围、正则；
• 埋点验证结果：验证结果提供双语格式，用户可自行选择中文或者英文；

埋点推送器

埋点推送器将“埋点验证结果”推送到前端，推送的过程存在数据交互频繁、数据体积大、数据传输稳定性的要求，这里我们自建 Push 服务进行数据传输，保证数据实时可达。

• 易用性：快速接入埋点验证，快速开始埋点验证
• 准确性：埋点验证结果准确、用户可信
• 实时性：埋点数据实时可见
• 稳定性：埋点数据可靠不丢失
• 扩展性：快速接入新的埋点数据格式

快速接入埋点验证，快速开始埋点验证

• 快速接入埋点验证
• SDK 提供“埋点验证开关”，客户端集成 SDK 的时候，可根据不同环境来配置是否开启“埋点验证开关”
• SDK 层判断如果开启“埋点验证开关”，埋点数据会双发，此过程对业务是透明的
• • 双发的原因或者为什么不从“线上埋点通道”取数？这里主要考虑两个原因：
  • • “线上埋点通道”数据量太大
    • SDK 层线上上报逻辑是采用微批的形式，默认 1 分钟从客户端上报一次，而埋点验证要求实时性，所以采用单独的通道

端	SDK	如何开启埋点验证开关
客户端	Android SDK IOS SDK	Android、IOS 提供 API，开关默认是关闭的，业务侧集成的时候可选择在“域内测试包”打开此开关
服务端	Go SDK Java SDK Python SDK	服务端会自行判断是否是非线上环境，如果是非线上环境，会默认开启“埋点验证开关”
web 端	JS SDK 浏览器插件	1. JS SDK 采用和客户端 SDK 一样的逻辑 2. 为了使用方便，我们也提供了浏览器插件，用户只需打开此插件即可，无需关注“埋点验证开关”

• 快速开始埋点验证
• • 建立 WS 连接：服务端和验证平台建立长连接，用于通信
  • ws_id：验证平台根据 ws_id 生成二维码
  • 扫码：客户端扫描二维码
  • 获取并打开验证开关：客户端获取设备信息并且打开埋点验证开关
  • 上报 device_id：客户端将长连接信息和设备信息上报至服务端
  • 下发 device_id：服务端将设备信息推送到验证平台
  • 开始验证：埋点验证平台进入验证阶段
  • 上报埋点：客户端开始上报埋点
  • 推送埋点：服务端将埋点推送到验证平台
• • 客户端上报的埋点数据中含有设备信息
  • 用户通过扫码在验证平台回填设备信息
  • 服务端接收到埋点数据后，将埋点数据中的设备信息和验证平台的设备信息进行匹配，如果匹配则将埋点数据进行下发

埋点验证结果准确、用户可信

埋点验证引擎必须保证埋点验证结果的准确性，才能降低验证成本。针对埋点数据本身的格式验证，我们采用了 JsonSchema 作为验证手段，以支持完善的验证规则、可信的验证结果。上文中的“规则生成器”、“规则选择器”、“埋点验证器”也都在一定程度上保证了埋点验证结果的准确性。

event:video_play

• 埋点名称：video_play
• • (名称、类型、是否必填、值校验、是否是场景条件)
  • enter_from,string,必传,固定值(login),是
  • duration,integer,必传,值无限制,否
  • type,integer,必传,枚举(1,2,3),否

jsonSchema

{
    "$schema":"https://json-schema.org/draft/2019-09/schema",
    "type":"object",
    "properties":{
        "params":{
            "type":"object",
            "properties":{
                "duration":{
                    "type":"integer"
                },
                "enter_from":{
                    "type":"string",
                    "enum":[
                        "login"
                    ]
                },
                "type":{
                    "type":"integer",
                    "enum":[
                        1,
                        2,
                        3
                    ]
                }
            },
            "required":[
                "duration",
                "enter_from",
                "type"
            ]
        }
    },
    "required":[
        "params"
    ]
}
复制代码

event:video_play

{
    "app_id":100,
    "event":"click",
    "params":{
        "enter_from":"login",
        "duration":1,
        "type":3
    }
}
复制代码

event:video_play

• 测试地址：www.jsonschemavalidator.net/

埋点数据实时可见

埋点验证场景下，服务端和验证平台需要频繁地进行数据交互，所以我们自建了 Push 服务(基于 WebSocket 的封装)，能够保证数据的实时畅通性

Push 服务目标

1. 基于 WebSocket 实现一套通用长连接通讯协议，能实现同一个客户端上的不同业务共享同一个长连接通道，并实现可靠的心跳机制。
2. 客户端和服务端基于通用长连接通讯协议实现一个稳定可靠的全双工通道。
3. 客户端实现一个通用的 SDK，服务端实现一个通用接入层。
4. 客户端 SDK，服务端接入层，都要很方便后续 service 接入。
5. Push 服务定期做打点监控，同时开放 http 的 Admin 接口，方便系统的监控和查看服务状态

Push 服务优势

1. 连接稳定性：Push 服务分为两个组件 Push 和 Backone，实现了业务和推送解耦。push 面向客户端连接，设计尽可能简单，需保持大量客户端活跃连接，避免了业务服务更新时不影响客户端连接
2. 服务隔离性：不同的业务服务接入 push 服务，会根据接入信息做集群隔离，避免业务之间互相影响
3. 横向扩展性：当业务服务不断增多时，只需对 push 服务做横向扩容即可支持

Push 服务流程

埋点数据可靠不丢失

1. 定义：服务级别协议 (service-level agreement，即 SLA) 是服务提供方与客户之间的正式承诺，用来量化服务水平(质量、可用性、责任)

2. 埋点验证服务：服务的特征是实时，所以衡量埋点验证不可用的手段是“数据延迟”，即埋点从“上报”->“验证平台”的 p99 超过 3s 即视为不可用，日常 p99 在 1s

   可用性	双月故障时间	年故障时间
   99.9%	86.4m	8.64 h

• 为了保证“SLA”，我们做了一系列的保护措施
• 日志转换器：客户端、服务端、web 端上报的是原始日志格式，需要转换为埋点验证日志格式后进行验证

措施	说明
监控	为了保证线上服务的稳定性，对线上流量进行监控，支持按 app 粒度进行查看 app 粒度的 QPS，以便发生报警的时候，可以快速定位到具体是哪个 app 的流量异常
报警	对线上流量进行报警，报警策略的设置如下：- 当前 QPS 达到最大 qps 的 50%的时候，报警级别为 warning，提示需要注意- 当前 QPS 达到最大 qps 的 70%的时候，报警级别为 critical，提示必须处理
限流	当发生报警的时候，通过监控定位出具体 app，做如下处理：1. 针对此 app 数据进行限流，确保其他 app 不会受到影响 2. 联系 app 业务方，确认此 app 流量是否为异常流量 3. 如果是异常流量，对异常流量进行处理，处理后撤销限流 4. 如果是正常流量，那么埋点验证服务进行处理
降级	实时验证流程是当前的主要业务，当发现流量突增，限流无法解决的情况下，对自动化验证流程进行降级，确保主要业务的稳定性

快速接入新的埋点数据格式

• 提供可插拔的“日志转换器插件”，服务高内聚，可支持各种日志格式快速接入、验证

埋点验证是保障埋点质量的有效方式，此方式属于事前验证，适用于埋点频繁变化的业务场景，需要一定程度的人工介入，能够解决基本的埋点质量问题。但是对于核心埋点场景来说，这种方式的验证成本较高，需要重复的人力投入，为了解决核心埋点验证成本高的问题，我们正在探索落地其他方式：

• 回归验证(自动化验证)：伴随每次发版，核心埋点都需要进行回归验证，目前我们通过内部其他团队的合作实现了自动化验证功能来支撑回归验证，当前已有一部分业务正在使用，极大地降低了验证核心埋点的成本
• 事后验证：经过事前验证、回归验证，埋点质量基本能得到很好的保障。但为了更好的保障我们也在探索事后验证的场景和落地：
• • 质量大盘：通过“规则引擎”，结合“质量模型”对埋点数据进行质量评估，得出各个维度的“质量评分”，然后针对质量问题进行专项修复，进一步提高埋点质量。
  • 质量工具：提供监控计划，业务可以针对自己关注的埋点配置监控报警，当线上出现质量问题，会发送质量报告给业务，及时止损。
• 全链路埋点质量保障：事前验证、回归验证、事后验证贯穿埋点的生命周期，打通这三个流程，从而形成埋点质量保障全链路，彻底解决埋点质量问题。