xlog-yl v0.0.21
体验技术中心
前端日志采集SDK使用说明(WEB\H5)
1 文档说明
1.1 编制说明
编写本文档的目的在于介绍如何在项目中接入前端日志SDK，采集上报日志。
1.2 文档结构
本文档主要为二个部分： 1) 如何接入SDK； 2) 如何使用SDK；
1.3 适用范围
本规范适用于指导前端研发人员日志采集工作。
2 SDK集成
2.1 仓库设置
在项目根目录添加文件 .npmrc，文件内容如下：（若文件已存在，则在文件末尾添加以下内容）
#xtc部门npm私服地址
registry=https://registry.npm.itbg2.ffcs.cn/
#屏蔽对https证书检查
strict-ssl=false
2.2 依赖安装
npm install @xtc/x-log --save
2.3 引入及初始化
2.3.1 在Vue项目中引入并初始化
在main.js中添加以下代码：
import xLog from ‘@xtc/xlog’
Vue.use(xLog, {
serverUrl: ‘http://localhost:8080’,
appName: ‘xtc-web’,
… // 其他参数，详见2.4章节
})
2.3.2 模块化引入并初始化
import xLog from ‘@xtc/xlog’
xLog.init({
serverUrl: ‘http://localhost:8080’,
appName: ‘xtc-web’,
… // 其他参数，详见2.4章节
})
2.3.3 CDN方式引入并初始化
下载dist目录下的xLog.min.js文件，放到项目 public 文件夹下(项目组也可自行决定存放目录)
xLog.init({
serverUrl: ‘http://localhost:8080’,
appName: ‘xtc-web’,
… // 其他参数，详见2.4章节
})
2.4 初始化参数配置说明
参数名称 类型 默认值 约束 说明
serverUrl string - 必填 日志上报服务地址
logMethod string /api/v1/fls/{logGroup}/{logTopic}/createLog 选填 日志上报接口名称
useAppTrack boolean false 选填 是否将日志发送到APP端
appName string - 必填 应用名称
appVersion string - 选填 应用版本
debug boolean false 选填 是否在控制台显示日志
reportImmediately boolean true 选填 是否采集日志后立即上报
maxCacheLength Number 5 选填 最大缓存日志条数
error boolean true 选填 是否采集错误日志
performance boolean false 选填 是否采集性能日志
pv boolean false 选填 是否采集访问日志
httpRequest boolean false 选填 是否采集API调用日志
event boolean false 选填 是否采集用户操作日志
2.4.1 serverUrl (日志上报服务地址)
初始化时，配置日志服务地址，例如serverUrl: http://127.0.0.1:8080，日志上报接口格式为：serverUrl+ logMethod。
2.4.2 logMethod (日志上报接口名称)
日志上报接口名称，默认值为：/api/v1/fls/{logGroup}/{logTopic}/createLog；日志上报时会默认取appName替换{logGroup}，logType替换{logTopic}。 若logMethod中不存在{logGroup}或{logTopic}，则不进行相应替换处理。
2.4.3 appName (应用名称)
初始化时，配置参数appName，即应用名称，例如：appName:xtc-web。
2.4.4 useAppTrack(是否将日志发送到APP端)
是否将日志发送到APP端，useAppTrack默认不开启，嵌入APP端的H5页面可配置useAppTrack: true，SDK采集日志后会调用APP的方法，将日志发往APP内，由APP进行上报日志。 注：若配置 useAppTrack: true，则无需再配置serverUrl、logMethod。
2.4.5 reportImmediately(是否立即上报)
是否采集日志后立即上报，初始化时，配置参数 reportImmediately：true，SDK在采集到一条日志后，会立即发送到后端； 配置参数 reportImmediately：false，SDK在采集到日志后，会先缓存在localstorage中，待满足条件后，批量上报日志；
2.4.6 maxCacheLength(最大缓存数)
最大缓存日志条数，初始化时，配置参数 reportImmediately：false，maxCacheLength: 5，SDK在采集到日志后，会先缓存在localstorage中，当缓存中的日志条数达到5条时，会向后端上报5条日志并清除缓存中已上报的日志。
2.4.7 Error(错误日志)
初始化时，配置参数 error:false，SDK不会自动采集页面的错误日志；
配置参数 error: true，SDK会自动采集页面的错误日志，主要采集3类错误：
1) 代码异常
采集的日志格式如下：
属性名称 值 说明
traceId 32位uuid 链路ID
userId 001 用户id
appName workShop 应用名
localTime 202211241100370014 日志产生时间
level error 日志级别
type errorLog 日志类型
eventType jsError 事件类型
errorMsg 错误信息
errorStack 错误堆栈
lineNo 3 错误行
columnNo 10 错误列
url http://localhost:3001 /index.html 出错文件或方法
osType 操作系统类型
userAgent 浏览器信息
title 当前页面标题
pageUrl 当前页面地址
2) 资源加载错误
采集的日志格式如下：
属性名称 值 说明
traceId 32位uuid 链路ID
userId 001 用户id
appName xtc-web 应用名
localTime 202211241100370014 日志产生时间
lotLevel error 日志级别
logType errorLog 日志类型
eventType resourceError 事件类型
nodeName script|link|img 元素节点名称
url http://localhost:3001 /img/demo.jpg 出错文件
osType 操作系统类型
userAgent 浏览器信息
title 当前页面标题
pageUrl 当前页面地址
3) promise调用链异常
采集的日志格式如下：
属性名称 值 说明
traceId 32位uuid 链路ID
userId 001 用户id
appName xtc-web 应用名
localTime 202211241100370014 日志产生时间
logLevel error 日志级别
logType errorLog 日志类型
eventType promiseError 事件类型
errorMsg 错误信息
errorStack 错误堆栈
osType 操作系统类型
userAgent 浏览器信息
title 当前页面标题
pageUrl 当前页面地址
2.4.8 pv(访问日志)
初始化时，配置参数 pv:false，SDK不会采集页面的访问日志；
配置参数 pv: true，SDK会在页面切换时，自动采集每个页面的访问日志。
采集的日志格式如下：
属性名称 值 说明
traceId 32位uuid 链路ID
userId 001 用户id
appName xtc-web 应用名
localTime 202211241100370014 日志产生时间
logLevel trace 日志级别
logType accessLog 日志类型
eventType openPage 事件类型
title 主页 页面标题
pageUrl http://localhost:3001/main 当前页面的url
fromPageUrl http://localhost:3001/index 来源页面的url
osType 操作系统类型
userAgent 浏览器信息
title 当前页面标题
pageUrl 当前页面地址
2.4.9 httpRequest(API接口请求日志)
初始化时，配置参数 httpRequest:false，SDK不会采集页面的API调用日志；
配置参数httpRequest:true,SDK会自动采集API调用日志，每发起一次API请求，就会生成一条日志。
采集的日志格式如下：
属性名称 值 说明
traceId 32位uuid 链路ID
userId 001 用户id
appName xtc-web 应用名
localTime 202211241100370014 日志产生时间
logLevel info 日志级别
logType httpRequestLog 日志类型
eventType xhr 事件类型
url /api/getInfoList 接口请求地址
method post 请求方式
requestBody {userName: “zhangsan”} 接口请求参数
requestHeaders {“method”: “post”} 接口请求的header内容
requestTime 1669258836888 接口请求时间
status 200 HTTP请求状态
responseHeaders {} 接口响应的body内容
responseBody {“code”: 200, “data”: {}} 接口响应结果
responseTime 1669258837045 接口响应时间
osType 操作系统类型
userAgent 浏览器信息
title 当前页面标题
pageUrl 当前页面地址
2.4.10 event(操作日志)
初始化时，配置参数 event:false，SDK不会自动采集操作日志；
配置参数 event:true，SDK会自动监听页面的点击事件，当点击的元素拥有属性 data-xlogger-track 时，SDK会记录此次点击事件，并将埋点的自定义数据记入日志。
采集的日志格式如下：
属性名称 值 说明
traceId 32位uuid 链路ID
userId 001 用户id
appName xtc-web 应用名
localTime 202211241100370014 日志产生时间
logLevel trace 日志级别
logType operationLog 日志类型
eventType click 事件类型
actionType xxx-click 控件名或方法名，同一页面内，需要唯一标识
behavior 点击新增用户按钮 行为描述
extra {} 自定义的埋点数据
osType 操作系统类型
userAgent 浏览器信息
title 当前页面标题
pageUrl 当前页面地址
埋点示例：
测试点击事件日志
2.4.11 performance(性能日志)
初始化时，配置参数 performance:false，SDK不会自动采集性能日志；
配置参数performance:true，SDK在进入页面时会自动采集基础的性能数据，通过浏览器的performance接口获取页面的性能数据。
采集的日志格式如下：
属性名称 值 说明
traceId 32位uuid 链路ID
userId 001 用户id
appName xtc-web 应用名
localTime 202211241100370014 日志产生时间
logLevel info 日志级别
logType performanceLog 日志类型
navigationStart 页面卸载完成所返回的时间点
unloadEventEnd 用户unload事件执行完成后的时间点
redirectStart 开始获取发起重定向的时间点
redirectEnd 重定向请求接收完最后一字节的时间点
fetchStart 浏览器查缓存之前的时间点
domainLookupStart 浏览器发起DNS查询的时间点
domainLookupEnd 结束DNS查询的时间点
connectStart 浏览器向服务器发起建立获取当前文档的连接请求的时间点
connectEnd 与服务器建立完成连接的时间点
requestStart 浏览器发起请求的时间
responseStart 浏览器拿到第一个响应字节的时间点
responseEnd 浏览器拿到最后一个响应字节或者传输连接关闭的时间点
domLoading 浏览器将当前文档状态设置成loading的时间点
domInteractive 浏览器将当前文档状态设置成interactive的时间点
domContentLoadedEventStart 浏览器触发DOMContentLoaded事件执行之前的时间点
domContentLoadedEventEnd 浏览器触发DOMContentLoaded事件执行完成的时间点
domComplete 浏览器将当前文档状态设置成complete的时间点
loadEventStart 浏览器触发load事件执行之前的时间点
loadEventEnd 浏览器触发load事件执行完成的时间点
osType 操作系统类型
userAgent 浏览器信息
title 当前页面标题
pageUrl 当前页面地址
2.5 手动埋点采集
若上述SDK提供的自动日志采集不满足需求，项目组也可以在需要采集日志的地方调用SDK提供的方法，手动埋点采集日志。
SDK对外提供的方法如下：
2.5.1 添加自定义日志
SDK提供了6个方法，开发人员可根据所需添加日志的级别，调用相应的方法：
xLog.trace() // 添加一条trace级别的日志
xLog.debug() // 添加一条debug级别的日志
xLog.info() // 添加一条info级别的日志
xLog.warn() // 添加一条warn级别的日志
xLog.error() // 添加一条error级别的日志
xLog.fatal() // 添加一条fatal级别的日志
2.5.1.1 参数说明
以上调用方法接收2个参数，第一个参数为logType (日志类型)，第二个参数为自定义采集的日志内容。
logType 参考值如下：
logType(日志类型) 说明
accessLog 访问日志
operationLog 操作日志
httpRequestLog 接口调用日志
errorLog 异常状态体制
performanceLog 性能日志
2.5.1.2 日志级别定义说明
日志级别 说明
trace(跟踪) 输出最细致的运行轨迹，可能包含涉及较多的程序追踪数据
debug(调试) 主要输出调试性质的内容，该级别日志主要用于在开发、测试阶段输出
info(通知) 主要用于记录系统运行状态等关联信息，一般通过该信息可以看到每个请求的主要执行过程
warn(警告) 潜在的危险或值得关注的信息，常用来表示系统模块发生问题，但并不影响系统运行
error(错误) 非预期中的错误，此种错误可能导致部分系统异常但不会影响核心业务和系统正常运行
fatal(致命错误) 用来输出非常严重或预期中不会发生的错误，遇到此种错误应当立即报警并人工介入处理
2.5.1.3 代码示例
1) Vue框架中使用
this.$xLog.trace('errorLog', {
… // 其他自定义参数
})
2) JS中使用
xLog.trace('errorLog', {
… // 其他自定义参数
})
2.5.2 设置用户信息
2.5.2.1 用户ID设置
若采集的日志需要携带用户信息，可以调用setUserId方法设置userId，调用之后，后续采集的每条日志都会携带userId。
代码示例：
1) Vue框架中使用
this.$xLog.setUserId(‘1001’)
2) JS中使用
xLog.setUserId(‘1001’)
2.5.2.2 用户信息设置
若需要记录更多的用户信息，可以调用setUserInfo方法。
代码示例：
1) Vue框架中使用
this.$xLog.setUserInfo({
userName: ‘zhangsan’,
userId: ‘1001‘,
email: ‘zhangsan@chinatelecom.cn‘,
…… // 其他用户信息
})
2) JS中使用
xLog.setUserInfo({
userName: ‘zhangsan’,
userId: ‘1001’,
email: ‘zhangsan@chinatelecom.cn’,
…… // 其他用户信息
})