Timepot


Time marker & report for page performance testing.

用于 Web 页面性能测速的打点统计及上报。

English Version(@todo) | 中文版

快速上手

示例代码

1. 安装

``
npm install timepot --save
`

2. 使用

引入timepot后，即可随时打点；在需要时输出或上报。

`
timepot.mark(); // anonymous mark
/ SOME CODE HERE /
timepot.mark('rendered'); // named mark

// promise api
timepot.timing().then(function(result) {
console.log(result);

// report to server
timepot.report('SOME_URL', timingData => {
// do some formatting for timing data that would be sent
return timingData;
});
});
`

简化的秒表模式

秒表模式：参数简化版，仅关注本次计时的 group 名称，不关心每个打点的命名，自动采用 tick + index 递增命名。

1. timepot.start('groupName')：开始统计，一个 groupName 仅调用一次
2. timepot.tick('groupName')：记下一个时刻，可多次调用 tick
3. timepot.stop('groupName')：结束统计，一个 groupName 仅调用一次

如对单个网络请求测速，在请求开始前timepot.start('cgi')，在获取到数据后timepot.stop('cgi')。

特点

* 简单易用，两种模式：打点模式和秒表模式
* 多节点：随时需要，随时mark
* 多实例：按group名称分组统计，互不干扰
* 数据完整：对接 performance 数据，优先基于PerformanceObserver获取完整数据
* 支持常见性能评估指标：对标Google RAIL 性能模型
* 优化上报方式：支持navigator.sendBeacon()上报，可降级为fetch、XHR
* 数据不丢失：支持延时批量上报，剩余未上报内容将会在页面beforeunload时发送

设计原理

数据结构
每个打点数据包装为一个Point，结构为：

`
Point = {
group: '', // optional, group name
name: '', // optional, name of this point
time: 0, // optional, current time in ms
duration: 0, // optional, time cost, calculate automatically
context: {} // optional, context data
}
`

每次timepot.mark()调用时，会写入一次上述结构，并计算duration的值。

内置有如下的group，注意不要覆盖：

- performance: 原始性能指标分组，对应常量timepot.GROUP_PERFORMANCE，window.performance.timing原始值的统计
- audits: 常见性能指标分组，对应常量timepot.GROUP_AUDITS，基于window.performance的进行关键性能指标计算后的统计
- default: 匿名分组，对应常量timepot.GROUP_DEFAULT，对于匿名（未命名）打点的统计结果

性能指标

根据 Navigation Timing Processing Model，对 RUM 进行计算的关键渲染路径指标 CRP 如下表。


| 指标 | 计算方法 | 含义
|-----------|---------------------------------------|-----------------
| unload | .unloadEventEnd - .unloadEventStart | 如果非直接打开时有值
| redirect| .redirectEnd - .redirectStart | 同上
| appCache| .domainLookupStart - .fetchStart | 读取缓存耗时，如果存在缓存，则直接跳到requestStart阶段
| DNS | .domainLookupEnd - .domainLookupStart | DNS查询耗时
| connect | .connectEnd - .connectStart | TCP建立连接耗时
| SSL | .connectEnd - .secureConnectionStart | 非https请求则无此项
| TTFB | .responseStart - .requestStart | 浏览器从发起请求到收到第一个字节的回包响应
| exchange| .responseEnd - .requestStart | 网络传输耗时，从发起请求，到收到所有回包内容
| DOMParse| .domInteractive - .domLoading | DOM解析时间
| DOMContentLoaded| .domContentLoadedEventStart - .domLoading | DOM 和 CSSOM均准备就绪
| DOMContentLoadedEvent| .domContentLoadedEventEnd - .domContentLoadedEventStart | DOMContentLoaded事件的执行耗时
| DOMComplete | .domComplete - .domLoading | 页面和所有子资源准备就绪
| loadEvent | .loadEventEnd - .loadEventStart | onload事件的执行耗时
| loaded | .loadEventEnd - .navigationStart | 页面加载完成总耗时
| FP | first-paint | 首次绘制
| FCP | first-contentful-paint | 首次内容绘制
| DNS::[domain] | .domainLookupEnd - .domainLookupStart | 每个域名下最耗时的域名查询，如果cache，则无此项
| exchange::[domain] | .responseEnd - .requestStart | 每个域名下最耗时的网络传输，context会列明具体的url、是否压缩、传输大小

API

配置参数

通过timepot.config的属性进行全局设置：

- enablePerformance：是否允许统计performance.timing数据，默认true
- enableSendBeacon：发送数据时，是否启用navigator.sendBeacon()方法，默认true
- enableFetch：发送数据时，是否启用fetch()方法，默认true
- reportPollingTime：上报的延时时间窗口，达到此阈值则上报，默认1000ms

方法

| 方法 | 作用 | 参数解释
|-----------------------------|----------------------|-----------------
| timepot.mark(name, point) | 打点 | name: optional，打点名称，无则匿名，会被统计为default分组；point：Optional，打点的其余信息
| timepot.start(group) | 计时器，开始 | group：required，String
| timepot.tick(group) | 计时器，打下一个计时点 | group：required，String，值同start
| timepot.stop(group) | 计时器，结束 | group：required，String，值同start
| timepot.timing() | 统计耗时，Promise 接口 | -
| timepot.report(url, dataHandler, options) | 上报数据 | url：上报的服务端地址；dataHandler ：上报的数据的处理函数，需要return有效上报值；options：选项，见下文
| timepot.stopReport() | 停止上报 | -
| timepot.getRawTimingData() | 获取原始测速数据 | -
| timepot.getTimingGroup(group) | 按分组获取测速数据 | group：required，String，分组名称
| timepot.getPerformance() | 获取performance性能测速数据 | -
| timepot.getAudits() | 获取常见性能指标数据 | -
| timepot.formatTimingDataByGroup(data) | 按group格式化原始测速数据 | data：required，Array，待格式化的原始测速数据
| timepot.clear() | 清除所有测速数据 | -
| timepot.console() | 以表格形式在控制台打印测速数据 | -

timepot.report()支持的 options：

* options.reportPollingTime: polling to report
* options.inRealtime: if need sent data in realtime
* options.enableSendBeacon: if enable navigator.sendBeacon()
* options.enableFetch: if enable fetch()

FAQ

1. 统计引入timepot之前的时间测速

在文档开始处（如)预埋小段代码，加载timepot后，对应的数据不会丢失；在完成timepot加载前，仅支持timepot.mark()方法。

`

`

2. 在一个页面区分多个统计实例

需要对每个实例进行命名，以group区分。

`
timepot.mark('start', { group: 'page' });
/ SOME CODE HERE /
timepot.mark('end', { group: 'page' });
`
如上，则以page聚拢此组统计，可通过timepot.getTimingGroup('page')`得到测速结果。

外部依赖

小巧，无外部依赖，原生实现。

License

MIT

If you have any questions that aren't covered here, please let me know.