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()方法。

<script type="text/javascript">
    window.timepot = window.timepot || [];
    timepot.mark = timepot.mark || function(name, point) {
        !point && (point = {});
        name && (point.name = name);
        point.time = Date.now();
        timepot.push(point);
    };
</script>

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.