shadow-tracker官网地址:点击这里
shadow-tracker代码仓库:点击这里
shadow-tracker 是一款前端监控框架,是一个轻量级的前端无感知监控插件,它提供的功能有:
序号 | 功能 | 对应日志类型 |
---|---|---|
1 | 收集用户与网页交互时的点击、键盘输入事件 | 事件日志(Event Log) |
2 | 收集所有 JS 的错误信息 | 错误日志(Error Log) |
3 | 收集所有 XMLHTTPRequest 网络请求信息 | 请求日志(XMLHttpRequest Log) |
5 | 收集页面加载的性能数据信息 | 性能日志(Performance Log) |
6 | 收集用户的设备信息 | 设备日志(Device Log) |
7 | 提供时间旅行功能,可根据用户的操作生成 NightWatch e2e 测试代码,复现用户的每一步操作 | 无 |
8 | 支持对日志的自定义拓展 | 无 |
备注:“页面的性能数据信息”日志功能支持 IE9 及以上浏览器,其他日志功能均支持 IE7 及以上浏览器。
npm install shadow-tracker
// 使用import引入tracker即可访问tracker的API
// 这里只呈现了“初始化tracker”以及“获取日志信息”的代码,其他API使用请参照第三部分“API说明”
import tracker from 'shadow-tracker'
tracker.init() // 初始化tracker
console.log(tracker.getLogList()) // 获取日志信息
标签引入<script src="./shadow-tracker-script.js">script>
<script>
// 引入之后tracker对象就会挂到window对象下,使用window.tracker即可访问tracker的API
// 这里只呈现了“初始化tracker”以及“获取日志信息”的代码,其他API使用请参照第三部分“API说明”
window.tracker.init() // 初始化tracker
console.log(window.tracker.getLogList()) // 获取日志信息
script>
注:由于服务器资源有限,建议先从"http://www.shadowingszy.top/ShadowTracker/script/shadow-tracker-script.js"
这里下载shadow-tracker脚本文件。
初始化 tracker
参数说明:
options - 传入一个配置项对象,详见第四部分“配置项说明”
使用样例:
tracker.init({})
获取用户设备信息并将设备信息写入 logList 中,详见第五部分“logList 说明及自定义 Log”
使用样例:
console.log(tracker.getDeviceInfo())
获取页面性能数据并将页面性能信息写入 logList 中,详见第五部分“logList 说明及自定义 Log”
使用样例:
console.log(tracker.getPerformanceInfo())
获取日志数据,详见第五部分“logList 说明及自定义 Log”
使用样例:
console.log(tracker.getLogList())
获取时间旅行代码,详见第六部分“时间旅行功能”
使用样例:
console.log(tracker.getTimeTravelCode())
在初始化 tracker 时,可传入配置项来丰富 tracker 的功能。
// 这是shadow-tracker的默认配置项,我们以此为例
const option = {
useClass: false, // 是否使用class作为元素的唯一ID
maxResponseTextLength: 1000, // 记录XMLHttpRequest返回值的最大长度
timeTracelInitTime: 3000, // 生成的时间旅行代码中,初始化页面的等待时间
timeTravelClickDelayTime: 1000, // 生成的时间旅行代码中,点击元素的延迟时间
timeTracelInputDelayTime: 1000, // 生成的时间旅行代码中,输入数据的延迟时间
custom: false, // 是否在日志对象中加入自定义数据
customizeLog: (logType, logContent) => {}, // 生成自定义log数据的函数,详见第五部分“logList 说明及自定义 Log”
customizeEventLog: (event) => {}, // 生成自定义event log的函数,详见第五部分“logList 说明及自定义 Log”
customizeErrorLog: (error) => {}, // 生成自定义error log的函数,详见第五部分“logList 说明及自定义 Log”
customizeXMLHttpRequestLog: (event) => {}, // 生成自定义XMLHttpRequest log的函数,详见第五部分“logList 说明及自定义 Log”
customizeDeviceLog: (userAgent) => {}, // 生成自定义device log的函数,详见第五部分“logList 说明及自定义 Log”
customizePerformanceLog: (performance) => {} // 生成自定义performance log的函数,详见第五部分“logList 说明及自定义 Log”
}
logList 是存储全部日志的 js 数组,我们可以使用getLogList()
来获取到这个数组,并针对自己的业务需求进一步开发日志上报、日志储存等逻辑。
另外,我们还可以根据自己的业务需求,对日志对象进行拓展。
如果我们需要添加自定义数据,首先我们需要把传入 tracker 的配置项对象中的custom
属性赋值为 true,并根据自己的需求实现自定义数据函数。
Log 对象是基础的日志对象,它包含如下属性:
{
"logTime": 1584262658187, // 日志产生的时间
"url": "www.shadowingszy.top", // 产生日志页面的url
"logType": "Error Log", // 日志的种类,包含:Event Log | Error Log | XMLHttPRequest Log | Device Log | Performance Log 五种
"logContent": {} // 日志的具体信息
}
自定义 Log 对象包含如下属性:
{
"logTime": 1584262658187, // 日志产生的时间
"url": "www.shadowingszy.top", // 产生日志页面的url
"logType": "Error Log", // 日志的种类,包含:Event Log | Error Log | XMLHttPRequest Log | Device Log | Performance Log 五种
"logContent": {} // 日志的具体信息
"custom":{ // 自定义日志字段
"log": {}, // 执行配置项中的customizeLog()方法后返回的值
"detail": {} // 某一类日志在执行配置项中的对应的customizeEventLog()、customizeErrorLog()、customizeXMLHttpRequestLog()、customizeDeviceLog()、customizePerformanceLog()方法后返回的值
}
}
通过实现配置项中的customizeLog
方法,我们可以自定义日志对象,并将customizeLog
函数的返回值作为 Log 对象中custom.log
属性的值。
customizeLog
方法参数说明:
参数名 | 参数类型 | 参数说明 |
---|---|---|
logType | string | 日志的种类,包含:Event Log | Error Log | XMLHttPRequest Log | Device Log | Performance Log 五种 |
logContent | object | 日志具体信息,即 Log 对象中的logContent 属性的值 |
Event Log 对象是记录用户点击、输入事件的日志对象,它会呈现在对应种类的 Log 对象的logContent
属性中。
Event Log 包含“点击”和“输入”两种日志类型,分别包含如下属性:
点击事件:
{
"domPath": "h1", // 当前事件的dom路径
"trackingType": "mousedown", // 事件类别
"offsetX": "0.5", // 当前点击事件的相对x坐标,如当前页面宽度是700,那么点击事件的x为350
"offsetY": "0.5" // 当前点击事件的相对x坐标,如当前页面宽度是700,那么点击事件的y为350
}
输入事件:
{
"domPath": "h1", // 当前事件的dom路径
"trackingType": "keyup", // 事件类别
"inputKey": "3", // 输入的值
"currentValue": "123" // 当前输入框的值
}
通过实现配置项中的customizeEventLog
方法,我们可以自定义日志对象,并将customizeEventLog
函数的返回值作为 Log 对象中custom.detail
属性的值。
customizeEventLog
方法参数说明:
参数名 | 参数类型 | 参数说明 |
---|---|---|
event | object | 当前触发事件的 event 对象 |
Error Log 对象是记录当前页面发生的 js 错误的日志对象,它会呈现在对应种类的 Log 对象的logContent
属性中。
Error Log 对象包含如下属性:
{
"errorType": "customize", // error的类型,包含:js | customize | window.onerror | window.onunhandledrejection 四种
"errorMsg": "This is error message", // 报错信息
"lineNumber": 0, // 出错位置所在行数
"columnNumber": 0 // 出错位置所在列数
}
注:errorType 详细说明
种类 | 说明 |
---|---|
js | javascript 代码报错 |
customize | console.error()报错,此种错误不包含错误堆栈信息 |
window.onerror | window.onerror 回调报错 |
window.onunhandledrejection | window.onunhandledrejection 回调报错 |
通过实现配置项中的customizeErrorLog
方法,我们可以自定义日志对象,并将customizeErrorLog
函数的返回值作为 Log 对象中custom.detail
属性的值。
customizeErrorLog
方法参数说明:
参数名 | 参数类型 | 参数说明 |
---|---|---|
error | object | 触发错误的 error 对象 |
XMLHttPRequest Log 对象是记录 XMLHttpRequest 的日志对象,它会呈现在对应种类的 Log 对象的logContent
属性中。
XMLHttPRequest Log 包含“请求开始”和“请求结束”两种日志类型,分别包含如下属性:
请求开始:
{
"event": "ajaxLoadStart" // 当前事件
}
请求结束:
{
"event": "ajaxLoadEnd", // 当前事件
"status": 200, // 状态码
"response": "" // 返回内容
}
通过实现配置项中的customizeXMLHttpRequestLog
方法,我们可以自定义日志对象,并将customizeXMLHttpRequestLog
函数的返回值作为 Log 对象中custom.detail
属性的值。
customizeXMLHttpRequestLog
方法参数说明:
参数名 | 参数类型 | 参数说明 |
---|---|---|
event | object | 触发ajaxLoadStart 或ajaxLoadEnd 的事件 |
Device Log 对象是记录用户设备信息的日志对象,它会呈现在对应种类的 Log 对象的logContent
属性中,包含如下属性:
{
"browser": true, // 是否为PC端浏览器
"mobile": false, // 是否为手机端浏览器
"type": "computer", // 当前终端的类别,包含:computer, ios, android, wechat, windows phone, unknow
"version": "80.0.3987.132", // 版本号
"name": "chrome", // 当前浏览器的类别,包含:msie, firefox, chrome, sarfari, android, ios, unknown
"userAgent": "" // navigator.userAgent的值
}
通过实现配置项中的customizeDeviceLog
方法,我们可以自定义日志对象,并将customizeDeviceLog
函数的返回值作为 Log 对象中custom.detail
属性的值。
customizeDeviceLog
方法参数说明:
参数名 | 参数类型 | 参数说明 |
---|---|---|
device | object | navigator.userAgent 对象 |
Performance Log 对象是记录页面性能数据的日志对象,它会呈现在对应种类的 Log 对象的logContent
属性中,包含如下属性:
{
"loadType": "reload",
"loadPageTime": 0, // 页面加载完成的时间
"domReadyTime": 0, // 解析 DOM 树结构的时间
"redirectTime": 0, // 重定向的时间
"domainLookupTime": 0, // DNS 查询时间
"timeToFirstByte": 0, // 读取页面第一个字节的时间,即用户拿到你的资源占用的时间
"requestTime": 0, // 内容加载完成的时间
"loadEventTime": 0, // 执行 onload 回调函数的时间
"cacheTime": 0, // DNS 缓存时间
"unloadTime": 0, // 卸载页面的时间
"connectTime": 0 // TCP 建立连接完成握手的时间
}
注:Performance Log 对象使用window.performance
来记录页面性能数据,因此只支持 IE9 及以上浏览器
通过实现配置项中的customizePerformanceLog
方法,我们可以自定义日志对象,并将customizePerformanceLog
函数的返回值作为 Log 对象中custom.detail
属性的值。
customizePerformanceLog
方法参数说明:
参数名 | 参数类型 | 参数说明 |
---|---|---|
performance | object | window.performance 对象 |
本功能会根据 logList 中的 Event Log 数据来复现用户的全部操作,并根据日志生成 NightWatch e2e 测试代码,我们只需要安装 NightWatch 并执行这部分代码,便可复现出用户的操作。
我们可以在 tacker 的配置项中进行参数设置。
参数名 | 参数说明 |
---|---|
timeTracelInitTime | 生成的时间旅行代码中,初始化页面的等待时间 |
timeTravelClickDelayTime | 生成的时间旅行代码中,点击元素的延迟时间 |
timeTracelInputDelayTime | 生成的时间旅行代码中,输入数据的延迟时间 |
生成代码示例:
function test(browser) {
browser
.url('www.shadowingszy.top')
.pause(3000)
.assert.elementPresent('#xml-test')
.click('#xml-test')
.pause(2000)
.assert.elementPresent('#get-log')
.click('#get-log')
.pause(2000)
.assert.elementPresent('#get-log')
.click('#get-log')
.pause(1000)
}