监控SDK这块，说白了就是给自己做的应用装上“监控探头”，前端、客户端、服务端都能用同一套思路去设计采集、汇总、上报。我最初接手这个项目时，起因是一次线上事故排查花了整整三天，最后发现是某类接口在特定环境下静默失败，用户操作完全没反应，但日志里什么都没有。从那时候开始，我决定自研一套轻量级监控SDK，把崩溃、错误、性能、用户行为这些关键数据全部捞上来，形成一套可追溯的可观测体系。
这篇文章我会完整复盘监控SDK开发过程中会涉及的核心设计、实现细节和我在生产环境里踩过的坑。适合正在自建可观测平台、准备从零开始做前端或客户端监控，或者想把现有埋点体系升级成真正可查询的监控系统的团队参考。文章偏实战，不会有太多空泛概念，每个模块都会给出可直接落地的设计思路和关键代码。
1. 监控SDK整体设计与思路拆解
1.1 监控SDK到底要采集什么数据
很多团队一开始做监控SDK，容易犯的一个错是什么都想采集，结果采集层越写越重，线上性能被拖垮。实际上监控数据按用途分其实就四类，每一类后续的数据处理方式完全不同。
第一类是异常错误数据，包括JS运行时错误、未捕获的Promise异常、资源加载失败、React/Vue等框架的错误边界捕获到的组件错误。这类数据的特点是量小、价值极高，每条错误都需要保留完整的堆栈、发生时的页面路由、用户操作路径、设备环境信息，用来做问题定位。
第二类是性能数据，包括首屏时间（FCP）、最大内容绘制（LCP）、累积布局偏移（CLS）、首次输入延迟（FID/INP）、接口请求耗时、页面卸载时间等。这类数据通常以数值型指标上传，需要带上时间戳和上下文信息，一是为了做趋势分析，二是为了在版本迭代后对比性能波动。
第三类是行为数据，例如点击事件、路由切换、控件曝光、关键业务流程流转。这类数据量最大，也是做用户行为分析的基础，但要特别注意隐私合规问题，不能采集输入框内容、密码等敏感数据。
第四类是环境信息，包括浏览器UA、操作系统、设备型号、分辨率、网络类型、语言、时区等。这类数据一般随每条上报记录附带上送，或者SDK启动时单独上报一次，用于问题时按环境维度过滤。
在设计采集模块时，我的建议是先把数据结构定义清楚，再动代码。每类事件都要有一个统一的事件模型，至少包含事件类型、事件名称、产生时间（毫秒级时间戳）、页面标识、用户标识（不涉及隐私）、会话ID，以及一个存放业务自定义字段的ext对象。
1.2 架构设计：采集、缓冲、上报三段式分离
监控SDK的原型可以拆成三个独立模块：采集器负责监听各种事件源；内部消息管道负责把采集到的数据统一转成事件对象；上报模块负责消费队列里的事件，按策略打包、序列化、发送。
为什么三段式必须分离？我踩过最深的坑是早期版本把采集和上报写在一个类里，结果某个上报失败重试的逻辑不小心阻塞了采集回调，监控SDK自己反而导致页面卡顿。采集器应该做成纯“生产者”，它只负责生成事件对象，丢到一个内存队列就返回，不做任何网络操作。上报模块作为“消费者”，通过定时器或者异步任务批量消费队列。
在具体实现上，我是用了一个简单的事件总线，内部维护一个事件数组，采集器调用一个emit方法把事件推入数组。上报模块周期性检查数组长度，达到阈值或到达时间窗口就flush。事件总线的核心代码并不多，但要保证push操作极快，不能做深拷贝，不能做序列化，这些开销全部延后到上报阶段。
内存队列的容量也需要控制。在4G内存的安卓设备上或者内存受限的旧手机上，如果用户短时间内触发大量事件，队列无限增长会撑爆内存。我设置了队列上限，默认2000条，超出的部分直接丢弃最老的事件，并且记录一条丢弃统计，随下次上报带出来，方便自己了解SDK丢了多少数据。
1.3 为什么不能直接把数据裸传给后端服务
新手写监控SDK最容易踩的坑就是直接把错误对象JSON.stringify之后POST到后端，这个做法问题非常多。
首先是上报稳定性问题。页面JS运行环境里，网络完全不可控，用户可能正在弱网环境，单条POST很容易失败，失败了没重试机制数据就丢了。其次是性能问题，每条错误单独上报意味着高频小包网络请求，对移动端用户的电量和流量都不友好。第三是隐私合规风险，如果采集器不小心抓到了敏感字段，直接上报可能造成数据泄露事件。最后是跨域问题，浏览器环境下跨域POST需要后端配CORS，如果上报路径和业务域名不同源，设置不对会导致全部上报失败。
合理的做法是“本地缓冲 + 批量上报 + 失败重试”的组合。SDK需要把事件先攒在队列里，按时间窗口（比如10秒）和数量阈值（比如10条）触发一次批量上报，网络错误时自动退避重试，超过最大重试次数后才丢弃，并记录一次丢数据统计。
还要注意上报请求本身必须走独立的通道，不能影响业务请求。我采用的方式是上报模块内部持有一个完全独立的fetch或者XHR实例，禁用缓存，设置超时，并且上传时使用sendBeacon作为兜底方案。
2. 核心细节解析与实操要点
2.1 错误捕获的完整链路与跨域陷阱
错误捕获是所有采集器里优先级最高的一块，因为监控系统存在的第一价值就是发现线上错误。不同运行环境下，错误来源完全不同。浏览器端的错误来源至少有四类：window.onerror能捕获到常规运行时错误；window.addEventListener('unhandledrejection')捕获未处理的Promise异常；元素上的error事件捕获资源加载失败；框架层的error边界捕获组件渲染错误。
我写采集器时把这四类都挂上了，但实际用下来发现真正的坑不在监听方式，而在跨域错误信息丢失。当一个脚本从CDN加载，而你的页面域名和CDN域名不一致时，浏览器出于安全考虑，会把错误信息统一替换成“Script error.”，堆栈、错误信息、行号列号全部丢失。这个问题排查起来极其痛苦，因为后端收到的数据看起来就是一条无任何信息的空错误。
解决方案有两个，必须在页面里显式给script标签加上crossorigin="anonymous"属性，同时CDN服务器必须返回Access-Control-Allow-Origin响应头。两个条件缺一不可。不过这只对当前页面加载的资源跨域脚本生效，动态创建的script标签同样需要处理，我统一封装了一个工具函数来处理所有script的跨域标记。
还有一个细节是window.onerror的第五个参数event对象，里面可能有更详细的信息，有些浏览器不传这个参数需要做兼容。我自己写了兼容逻辑，各种参数缺失时以可获取的信息为准，宁可少字段也不能让SDK本身抛异常中断采集流程。
2.2 性能数据采集：黄金指标与PerformanceObserver的坑
性能监控是监控SDK的重头戏，也是用户感知最明显的一块。核心指标是谷歌Web Vitals主推的FCP、LCP、CLS、INP，再加上首屏时间和接口耗时。
采集方式主要依赖PerformanceObserver，它比手动计算时间戳更可靠，因为浏览器把各阶段的精确时间点都算好了，直接订阅对应entryType即可。需要注意的一点是，PerformanceObserver的回调是异步触发的，而且受浏览器自身调度影响，在极端情况下可能延迟几十毫秒才回调，但精确度仍然远高于自己记录Date.now()。
性能采集器最大的坑是观察的时机。PerformanceObserver在对象创建时并不会立刻收到历史性能条目，必须传入buffered: true才能拿到观察之前的存量数据；同时首屏指标LCP在页面加载完成后还可能在用户交互后更新，所以需要监听disconnect时机，或者在用户首次输入时主动disconnect并取出最终值。
另一个容易踩的是跨域资源对性能条目的影响。如果页面引用了跨域CDN图片或字体，PerformanceObserver拿到的LCP条目中，资源详情可能被遮挡成空白或者不完整的时间信息，这同样需要timingAllowOrigin配合服务器响应头才能拿到准确的资源加载耗时。
2.3 网络请求监控与接口耗时分析
接口监控是整个监控SDK里业务价值最高的模块，因为绝大多数“页面卡了”“白屏了”的问题，最后都能归因到某个接口慢或者挂掉。前端环境下要捕获所有请求，最合适的切入点就是包裹XMLHttpRequest和fetch两个全局对象。
包裹XHR时要注意几个点：open、send、setRequestHeader都要做一层代理，不能在原方法上直接改写。在load事件里读取responseURL和status，在error事件里记录失败。传递给后端的数据至少包括请求方法、请求URL（不含query里的敏感参数）、状态码、耗时、请求体大小、响应体大小、错误类型。
fetch拦截相对简单一些，可以在window.fetch上包一层，先调用原始fetch拿到Promise，在then回调里等response实际解析后记录耗时和状态码。这里一个容易忽略的问题是fetch成功返回不代表请求成功，HTTP 500同样会走then，只有网络层错误才走catch，所以必须把HTTP状态码也作为成功与否的判断条件。
拦截手段是补丁式实现，理论上业务代码如果直接调用XMLHttpRequest.prototype上的方法绕过自定义实例，拦截会失效。不过实际开发中这种用法极少，而且SDK本身不因拦截失败而崩溃即可。
接口监控的数据量相对大，我做了两层压缩：URL按规则聚合，去掉实际参数值保留路径结构；耗时按区间分桶记录，这样在上报时能显著压缩体积。
3. 实操过程与核心环节实现
3.1 从零搭建监控SDK的最小骨架
我建议把目录拆成core、collectors、transport、utils四块。core负责事件总线和主流程初始化；collectors按功能拆分成错误采集器、性能采集器、行为采集器、请求采集器；transport负责上报队列、序列化、网络发送；utils放公共工具函数。
事件总线的核心逻辑大概这样：
class EventBus { constructor () { this.queue = []; this.maxLen = 2000; this.discardCount = 0; } emit (event) { if (this.queue.length >= this.maxLen) { this.discardCount++; this.queue.shift(); } this.queue.push(event); if (this.queue.length >= this.flushThreshold) { this.flush(); } } flush () { if (this.queue.length === 0) return; const batch = this.queue.splice(0, this.queue.length); transport.send(batch).catch(() => { // 失败时重新放回队列，但要限制重试次数 }); } }init初始化时会把所有采集器都注册到EventBus上。采集器内部监听到事件后，emit到总线立即返回。SDK的启动方式建议用同步初始化加异步采集，确保用户无感知。页面加载时SDK自身初始化造成的开销必须控制在毫秒级，绝对不能因为引入监控SDK让首屏变慢。
3.2 上报通道：sendBeacon、fetch与1x1 GIF的选择
上报通道的选择直接影响数据到达率。页面卸载时发请求，常规fetch很可能被浏览器取消，因为页面上下文已经没了。这个问题没有完美的JS解决方案，但sendBeacon从设计上就是为这个场景准备的，它会在浏览器后台把数据发送出去，不阻塞页面卸载，而且不需要等待响应。
我的方案是把sendBeacon作为首选项。兼容性上，现代浏览器基本都支持，但存量用户要看情况。sendBeacon不支持自定义请求头，所以需要传复杂数据时只能走data参数或者直接用Blob类型。如果需要携带自定义Header，退回用fetch，通过keepalive: true参数让浏览器在卸载阶段也尝试发送。
还有一种极老套但极其稳定的方式是1x1 GIF上报。原理是创建一个Image对象，把数据编码到URL的query参数里，浏览器加载图片的请求不会被CORS拦截，而且天然兼容所有浏览器环境。缺点是URL有长度限制，优雅地处理大批量数据时不如sendBeacon和fetch。我保留了GIF上报作为最底层兜底，但正常情况下不会触发。
无论哪种通道，上报请求都必须在服务端返回一个极小的200响应。监控SDK有大量小请求，如果不做服务端优化，光日志可能就把监控后端打爆。
3.3 上报数据格式与批量打包策略
数据格式建议褒义JSON，协议上固定一个版本号，方便后端解析兼容。单个事件对象如果包含完整的堆栈、性能数据、环境信息，序列化后的大小通常几百字节到几KB不等。批量上报时，我把同类型的事件合并成一个数组，数组外层再加一层通用字段，包括SDK版本、上报时间、批量计数、环境信息。
为了压缩体积，字段名全部用短名，比如eventType缩写为et，timestamp缩写为ts，pageUrl缩写为pg。这个做法在数据量大时效果显著，接口监控一天可能产生几万条事件，每个字段少写几个字符，整体数据量能减少30%以上，流量费用就下来了。
批量打包的时间策略是双条件触发：时间阈值和数量阈值。默认时间阈值10秒，数量阈值10条。只要两个条件任一满足就触发一次flush。很多团队用固定间隔，但固定间隔在页面刚加载时会导致频繁空请求，双条件策略在低数据量时能显著减少空跑。
3.4 采样策略与用户隐私保护
全量上报任何数据都不现实。以行为采集器为例，用户一次完整交互可能产生几十条事件，全部上报会淹没后端。我的策略是分三层：错误和重要性能指标全量采集；接口监控全量采集但字段精简；行为数据按会话维度采样，默认30%采样率。
采样率设计上用用户ID哈希取模，保证同一个用户要么全部上报，要么全部不上报，不会出现同一条用户路径数据支离破碎的情况。错误和性能数据不做采样，因为这类数据量本身不大，但价值极高，一旦采样会漏掉关键问题。
隐私合规方面，所有采集器默认不采集输入框内容、密码、验证码、个人身份字段，URL地址全部去掉query参数。上传前再做一次字段白名单校验，不在名单里的字段直接丢弃。这个校验放在transport层或序列化层统一处理，后续如果业务方需要新增字段，只要在配置里显式声明才会被放行。
4. 常见问题与排查技巧实录
4.1 数据上报丢失与重复上报如何排查
监控SDK最容易被质疑的就是数据怎么又不见了。我排查下来大部分情况不是真丢，而是链路断了。
上报丢失的三种常见情况：第一种是用户页面打开时间极短，页面还没触发批量上报用户就已关掉页面，sendBeacon特性在移动端某些内置浏览器并不完全可靠；第二种是批量上报时请求体过大，部分服务端网关或代理对单次POST数据量有限制，超过限制直接断开连接；第三种是弱网络环境下重试策略过于激进，导致网络拥塞时全部超时。
我的处理方式是多管齐下：批量上报的上限控制在单次不超过1MB，超过就切分；失败重试采用指数退避，从2秒起步，最多重试3次；关键事件里加一个uniqueId字段，服务端按uniqueId做幂等去重。uniqueId的生成规则是按设备ID、会话ID、事件类型、自增序号拼接，同一事件即使被重试发送多次，服务端也只会保留一条。
重复上报的根源则恰好相反，通常是SDK在页面初始化时重复执行了多次，事件总线里产生了多份监听。早期版本我遇到过某个框架路由切换时重新实例化SDK，导致同一个错误被上报了三份。现在的做法是SDK全局只允许初始化一次，init之前判断全局flag，已经初始化则直接返回同一个实例。
4.2 生产环境“Script error.”的处理全流程
“Script error.”这个问题我在2.1里提过，这里专门说一下完整处理流程。当你看到后端监控面板里大量Script error.却完全不知道什么错时，不要慌，按以下顺序排查。
第一步，确认页面中加载的所有跨域脚本是否都带上了crossorigin="anonymous"属性。第二步，确认CDN或静态资源服务器是否响应Access-Control-Allow-Origin:*。第三步，确认动态创建的script标签、通过import()动态加载的模块同样满足前两步要求。第四步，如果上述都没问题，那要看错误是否来自第三方SDK的内部脚本，有些第三方SDK的JS文件本身不设置CORS响应头，外部无法拿到详细错误，这类情况只能在脚本加载时做Promise封装，捕获加载失败事件单独上报。
另外有个容易被忽略的场景是source map。拿到错误之后，线上的代码全是压缩后的变量名，不还原根本看不出错误位置。我的做法是错误上传时带上原始文件的绝对路径和行列号，后端根据source map文件还原原始代码位置。source map文件绝不能公开部署到静态目录，否则等于把源码交了出去，我通常会存到内部对象存储或单独的服务端目录里，只供后端解析使用。
4.3 上报逻辑拖慢页面性能的排查思路
监控SDK成了性能杀手，这个事在圈子里常被吐槽。我运营SDK的早期版本就出过这种问题。排查下来原因很集中：序列化大对象太频繁、上报请求占满了网络通道、采集器回调中塞了重逻辑。
我的优化原则是“采集线程和IO完全隔离”。事件总线emit只做数组push，序列化只在flush时做。存在大量行为数据时，序列化改成流式处理，每批只处理一小段，分散到多个宏任务里执行，避免一次JSON.stringify几万条数据导致主线程长时间阻塞。
上报请求对业务请求的影响，在浏览器环境下实际是HTTP连接数限制，每个域名有并发上限，如果SDK的批量上报占满了连接数，业务请求就得等到排队。解决办法是上报域名单独用一个CDN或者子域，比如monitor.example.com，与业务主域分的越开越好，同时只保留两个并发连接，用队列控制发送节奏。
还有一个隐蔽的性能陷阱是错误堆栈的自定义序列化。默认的stack是个长字符串，直接上传会造成大量重复内容。我在上传前会做一次堆栈压缩，把重复出现的相同调用帧去重，只保留首次出现的路径，实测对压缩体积效果非常明显。
4.4 监控SDK自身的保命机制：熔断与自我保护
监控SDK是寄生在业务代码里的，SDK自己出问题就是事故放大器，所以必须给它配一套保命机制。
全局保护是第一条防线。所有采集回调、序列化逻辑、网络发送逻辑都用统一的方法包裹try/catch，捕获到异常时直接静默丢弃，绝不让SDK的错误逃到业务代码中。SDK内部可以维护一个错误计数器，连续出错的次数超过阈值时自动关停整个SDK，避免无效重试反复影响业务。
防死循环是个容易踩的坑。我见过一个极端案例，SDK捕获错误后上报，上报失败又触发异常，异常又触发上报，最终形成了一个死循环。保命机制里要显式标记“正在上报”状态，上报期间捕获到的新错误只入队不触发新的上报流程，等当前批次结束后统一处理。这个标记用标志位实现即可，简单有效。
最后是通信协议上的保护。所有上报请求都通过独立通道发送，与业务请求互不影响。服务端返回的响应中包含一个版本控制字段，如果SDK版本过旧，服务端会通知SDK降级上传频率，甚至关闭周期性采样，只保留错误采集，确保即使SDK存在Bug，影响范围也可控。
5. 监控SDK从能用到好用：体验与效率优化
好的监控SDK不只是“能采集数据”，更要在日常使用中让人愿意去维护它。我自己在持续迭代这套SDK的过程中，积累了几个对未来规划意义比较大的方向。
埋点配置化是最近重点做的事。以前每增加一个埋点需求，都要重新发版SDK，效率太低了。现在所有采集规则都改成配置下发，后端可以动态控制某个事件类型是否开启、采样率是多少、字段黑名单有哪些。比如某个页面流量特别大，我可以从后台直接把行为采样率降到10%，完全不用等业务发版。这个能力上线后反馈非常好，监控人员终于可以自主调整采集策略了。
可视化面板和告警规则的联动同样值得投入。数据采集上来若只是堆在数据库里，价值大打折扣。我做的告警模块支持按接口耗时的P95、错误率突变、特定路由异常等维度配置规则，命中后自动推送到IM群。这个功能上线后，团队对线上问题的感知时间从小时级缩短到了分钟级。
服务质量监控如果把前端性能和用户体验指标纳入，还能反向驱动优化。接口慢到底是因为后端变慢，还是网络传输问题，配合traceId做前后端链路串联就能精确定位层。虽然这套做起来成本不低，但一旦打通“用户反馈-数据定位-修复验证”的闭环，监控SDK就从一个采集工具变成了一套完整的产品。
最后再分享一个我对监控SDK开发整体难度的真实感受。难度不在于某个单一技术的实现，而是把所有细节整合到一起还不出问题，并且能在恶劣网络条件下稳定运行。如果你也准备自研监控SDK，我的忠告是先明确自己的数据模型和数据用途，把SDK的边界画清楚，再动手写代码。宁可一开始少做几项监控，也别让SDK存在任何影响业务性能的隐患。这行做得越久，越明白“监控系统自己也必须是被监控的对象”这句话的分量。
