@arms/js-sdk

ARMS RUM

    ___     ____   __  ___ _____    ____   __  __ __  ___
   /   |   / __ \ /  |/  // ___/   / __ \ / / / //  |/  /
  / /| |  / /_/ // /|_/ / \__ \   / /_/ // / / // /|_/ / 
 / ___ | / _, _// /  / / ___/ /  / _, _// /_/ // /  / /  
/_/  |_|/_/ |_|/_/  /_/ /____/  /_/ |_| \____//_/  /_/   

开始使用

申请阿里云前端监控PID

阿里云业务实时监控服务(ARMS)前端监控平台专注于 Web 端体验数据监控，从页面打开速度（测速）、页面稳定性（JS Error）和外部服务调用成功率（API）这三个方面监测 Web 页面的健康度。

您可以在这里了解我们的应用.

在接入之前请确保您已经申请待接入站点唯一PID

如果需要申请PID，可以参看帮助文档

cdn引入

在页面头部或 body 第一行引入脚本：

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"站点唯一ID"};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
</script>

npm包引入

const BrowerLogger = require('@arms/js-sdk');
// BrowserLogger.singleton(conf) conf传入config配置
const __bl = BrowerLogger.singleton({
    pid: 'your-project-id',
    imgUrl: 'https://arms-retcode.aliyuncs.com/r.png?', // 设定日志上传地址,新加坡部署可选`https://arms-retcode-sg.aliyuncs.com/r.png?`
    // 其他config配置
});

• 默认会开启 fetch 和 XMLHttpRequest 的请求上报，以及页面 JS Error 的上报；
• 站点 ID 会在 ARMS 后台创建的时候自动生成，是当前站点的唯一标识

config配置项

参数名	类型	描述	是否必须	默认值
pid	String	项目唯一 ID，由 ARMS 在创建站点时自动生成	是	无
page	String	页面名称，默认取当前页面 URL 的关键部分	否	host + pathname
sample	Integer	日志采样配置，值1/10/100，性能和成功API日志按照1/sample采样，即1表示100%采样,10表示10%采样，100表示1%采样	否	1
enableSPA	Boolean	是否监听页面的 hashchange 事件并重新上报 PV，适用于单页面应用场景	否	false
parseHash	Function	配合 enableSPA 使用，详情见下文	否	见下文
disableHook	Boolean	是否禁用 AJAX 请求监听，默认会监听并用于 API 调用成功率上报	否	false
autoSendPv	Boolean	是否初始化后自动发送 PV，默认会自动发送	否	true
sendResource	Boolean	是否上报资源数据，默认不上报	否	false
ignoreUrlCase	Boolean	是否忽略page url大小写，默认忽略	否	true
urlHelper	*	URL 规整规则，详情见下文	否	见下文
apiHelper	*	API 规整规则，详情见下文	否	见下文

部分设置项详细说明

1. parseHash 将URL hash 解析为page的方法

此参数用于单页面应用场景中，在设置了 enableSPA 为 true 的前提下，页面触发 hashchange 事件时，将 URL hash 解析为 page 字段的方法。

默认值是一个简单的字符串处理方法：

function (hash) {
    var page = hash ? hash.replace(/^#/, '').replace(/\?.*$/, '') : '';
    return page || '[index]';
}

此项一般情况下不需要修改，不过如果需要在上报时使用自定义的页面名，或者 URL 的 hash 比较复杂（ 例如 /aaa/bbb/:id?t=xxx ），则需要修改此配置项。

示例：

// 定义页面 hash 和 page 的映射关系
var PAGE_MAP = {
    '/': '首页',
    '/contact': '联系我们',
    '/list': '数据列表',
    // ...
};

// 页面 onload 后调用 SDK 方法
window.addEventListener('load', function (e) {
    // 调用 setConfig 方法修改 SDK 配置项
    __bl.setConfig({
        parseHash: function (hash) {
            key = hash.replace(/\?.*$/, '');
            return PAGE_MAP[key] || '未知页面';
        }
    });
});

2. urlHelper URL规整规则，代替原ignoreUrlPath

在页面 URL 类似于 http://xxx.com/projects/123456 这样的场景中（projects 后面紧跟的是项目 id）， 如果将 xxx.com/projects/123456 作为 page 上报，会导致在数据查看时页面无法聚成一类，所以需要过滤掉这些非关键字符。

此设置项只在自动获取页面URL作为page时才会生效，如果手动调用 setPage 或 setConfig 方法修改过 page，或者设置了 enableSPA 的值为 true，则此设置项无效。

默认值是一个数组，一般情况下不需要修改：

[
    // 将所有 path 中的数字变成 *
    {rule: /\/([a-z\-_]+)?\d{2,20}/g, target: '/$1**'},
    // 去掉 url 末尾的'/'
    /\/$/
]

此设置项的默认值会过滤掉类似 xxxx/123456 后面的数字，比如 xxxx/00001 和 xxxx/00002 都会变成 xxxx/**。

urlHelper 的值可以是多种类型，用法分别为：

• String 或 RegExp: 将匹配到的字符串去掉；
• Object<rule, target>: 对象包含两个 key，分别是 rule 和 target，作为 JS 字符串的 String::replace 方法的入参；
• Function: 将原字符串作为入参执行方法，将执行结果作为 page；
• Array: 用于设置多条规则，每条子规则的都可以是上述类型之一。

3. apiHelper api规整规则，代替原ignoreApiPath

用于在自动上报 API 的时候过滤掉接口 URL 中的非关键字符，用法及含义同 urlHelper

默认值是一个对象，一般情况下不需要修改：

{rule: /(\w+)\/\d{2,}/g, target: '$1'}

此设置项的默认值会过滤掉接口 URL 中类似 xxxx/123456 后面的数字。

4. config.sendResource 资源上报, 用于慢会话追踪

是否上报资源数据，默认不上报. 如需启用慢会话追踪，需要开启此项(注: 目前新加坡region暂不支持此功能).

开启上报后，会依据apdex选择性上报资源数据

• Satisfied(0-2s): 不上报
• Tolerating(2-8s): 50%上报
• Frustrated(>8s): 100%上报

API 接口

通用 API

1. @static singleton() 获取单例对象

*该方法只适用于npm引入

调用参数说明：BrowerLogger.singleton(config,prePipe)

静态方法，返回一个单例对象，只在第一次调用时传入的config,prePipe生效，之后调用只返回已经生成的实例：

参数	类型	描述	是否必须	默认值
config	Object	站点配置, 其他配置查看 #config配置项	是	-
prePipe	Array	预上报内容	否	-

此方法可以用于在应用入口初始化 SDK，也可以在每次调用时获取实例。

2. setConfig() 修改配置项

用于在 SDK 初始完成后重新修改部分配置项，具体配置请参照 SDK 配置项。

调用参数说明：__bl.setConfig(next)

参数	类型	描述	是否必须	默认值
next	Object	需要修改的配置项以及值	是	-

示例：修改 disableHook 禁用 API 自动上报

__bl.setConfig({
    disableHook: true
});

3. setPage() 设置当前页面的page name

用于重新设置页面的 page（默认会触发重新上报 PV），此接口一般在单页面应用中会用到。

调用参数说明：__bl.setPage(next, sendPv)

参数	类型	描述	是否必须	默认值
page	String	新的page name	是	-
sendPv	Boolean	是否上报PV，默认会上报	否	true

示例：

// 设置当前页面的 page name 为当前的 URL hash，并重新上报 PV
__bl.setPage(location.hash);

// 仅设置当前页面的 page 为'homepage'，但不触发 PV 上报
__bl.setPage('homepage', false);

4. removeHook() 移除当前实例上的自动 API 上报

如果需要手动上报 API 监听数据，则可以调用此方法移除自动上报监听（推荐在初始化配置中直接设置 disableHook 为 true）

__bl.removeHook();

5. addHook(isForce) 在当前实例上挂载 API 监听的 hook

用于多实例的场景，将 API 监听的 hook 从一个实例上移除后，挂载到另一个实例上，如果 isForce 为 true，则强制将挂载实例指向自己

__bl.addHook(true);

6. createInstance(config) 创建一个新的 BrowserLogger 实例

创建一个新的实例，新的实例默认继承当前实例的 pid，用于单页面应用需要分区块上报的场景

// 创建一个新的实例
var sdk2 = __bl.createInstance({
    tag: 'sdk2',
    page: 'another_page' // 如果设置了 page，则会自动上报一次 PV
    // ...
});

数据上报接口

1. api() 接口调用成功率上报

此接口用于上报页面的 API 调用成功率，SDK 默认会监听页面的 AJAX 请求并调用此接口上报； 如果页面的数据请求方式是 JSONP 或者其它自定义方法（比如客户端 SDK 等），可以在数据请求方法中调用 api() 方法手动上报。

另外，如果要调用此接口，建议在 SDK 配置项中将 disabledHook 设置为 true，具体配置请参照 SDK 配置项。

调用参数说明：__bl.api(api, success, time, code, msg)

参数	类型	描述	是否必须	默认值
api	String	接口名	是	-
success	Boolean	是否调用成功	是	-
time	Number	接口耗时	是	-
code	String/Number	返回码	否	''
msg	String	返回信息	否	''

示例：

var begin = Date.now(),
    url = '/data/getTodoList.json';

ajax(url, {id: 123456}).then(function (result) {
    var time = Date.now() - begin;
    // 上报接口调用成功
    window.__bl && __bl.api(url, true, time, result.code, result.msg);
    // do something ....
}).catch(function (error) {
    var time = Date.now() - begin;
    // 上报接口调用失败
    window.__bl && __bl.api(url, false, time, 'ERROR', error.message);
    // do something ...
});

2. error() 错误信息上报

此接口用于上报页面中的 JS 错误或者使用者想要关注的异常；

一般情况下，SDK 会监听页面全局的 Error 并调用此接口上报异常信息，但由于浏览器的同源策略往往获取不到错误的具体信息，这时就需要使用者手动上报。

调用参数说明：__bl.error(error, pos)

参数	类型	描述	是否必须	默认值
error	Error	JS 的 Error 对象	是	-
pos	Object	错误发生的位置，包含以下 3 个属性	否	-
pos.filename	String	错误发生的文件名	否	-
pos.lineno	Number	错误发生的行数	否	-
pos.colno	Number	错误发生的列数	否	-

示例：监听页面的 JS Error 并上报

window.addEventListener('error', function (ex) {
    // 一般事件的参数中会包含 pos 信息
    window.__bl && __bl.error(ex.error, ex);
});

示例2： 上报一个自定义的错误信息

window.__bl && __bl.error(new Error('发生了一个自定义的错误'), {
    filename: 'app.js', 
    lineno: 10, 
    colno: 15
});

3. speed() 自定义测速上报

此接口用于上报页面中的一些自定义的关键时间节点；

调用参数说明：__bl.speed(point, time)

参数	类型	描述	是否必须	默认值
point	Enum	测速关键字，必须是 s0 ~ s10	是	-
time	Number	耗时(毫秒)，默认是当前时间 - 页面起始时间	否	Date.now() - startTime
forceSPA	Boolean	只在 SPA 中有效，上报数据时 page 是否使用子页面	否	false

示例：

__bl.speed('s0');

__bl.speed('s1', 1024);

4. sum() 求和统计

此接口用于统计业务中的某些事情发生的次数

调用参数说明：__bl.sum(key, value)

参数	类型	描述	是否必须	默认值
key	String	事件名	是	-
value	Number	单次累加上报量，默认 1	否	1

示例：

__bl.sum('event-a');

__bl.sum('event-b', 3);

__bl.sum('group-x::event-c', 2);

4. avg() 求平均统计

此接口用于统计业务场景中某些事情发生的平均次数或平均值

调用参数说明：__bl.avg(key, value)

参数	类型	描述	是否必须	默认值
key	String	事件名	是	-
value	Number	统计上报量，默认 0	否	0

示例：

__bl.avg('event-a', 1);
__bl.avg('event-b', 3);

__bl.avg('events::event-c', 10);
__bl.avg('speed::event-d', 142.42);

5. percent() 百分比统计

此接口用于统计业务场景中某一类事件下的各自占比

调用参数说明：__bl.percent(key, subkey, value)

参数	类型	描述	是否必须	默认值
key	String	事件名	是	-
subkey	String	事件成员	是	-
value	Number	单次累加上报量，默认 0	否	0

示例：

__bl.percent('gender', 'm', 1);
__bl.percent('gender', 'f', 3);

FAQ

1. 单页面应用 (SPA) 如何分开统计 PV?

在 SPA（ Single Page Application ）中，页面只会刷新一次；传统的方式只会在页面加载完成后上报一次 PV，而无法统计到各个子页面的 PV，也无法让其它类型的日志聚类到对应的子页面。

SDK 提供了两种 SPA 页面的处理方式：

1. 开启 SPA 自动解析

此方法适用于大部分以 URL hash 作为路由的单页面应用场景。

在初始化的配置项中，设置 enableSPA 为 true，即会开启页面的 hashchange 事件监听（触发重新上报 PV），并将 URL hash 作为其它数据上报中的 page 字段；

另外，与 enableSPA 相配套的还有 <Function>parseHash，参见 SDK 配置项

2. 完全手动上报

此方法可用于所有的单页面应用场景，如果方法一无法满足，可用此方法。

SDK 提供了 setPage 方法来手动更新数据上报时的 page name，调用此方法时，默认会重新上报页面 PV。

示例：

// 监听应用路由变更事件
app.on('routeChange', function (next) {
    __bl.setPage(next.name);
});

另外，对于页面初始化完成后的第一次 PV 上报，如果也想要手动控制，可在配置项中设置 autoSendPv 为 false，然后在应用初始化完成后，调用 setPage

2. 解决 JS Error 跨域获取不到的问题

由于浏览器的安全策略，SDK 无法获取到其它 host 下的 JS Error 的错误信息，解决办法：

在 script 标签上添加 crossorigin 属性：

<script src="xxx" crossorigin></script>

以上只能解决部分问题，实际情况下还是无法获取具体的错误信息，另一种办法就是用户在自己的 JS 中监听 JS Error，然后上报：

window.addEventListener('error', function (e) {
    window.__bl && __bl.errorHandler(e);
});
window.addEventListener('unhandledrejection', function (e) {
    window.__bl && __bl.errorHandler(e);
});

3. 如何在 SDK 初始化前预上报数据？

• cdn引入

场景一：

在页面刚刚加载时，有一些数据需要上报，此时 SDK 可能还未初始化完成（或者不确定是否初始化完成）。

场景二：

在应用的初始化逻辑中调用 setConfig 方法，但由于 SDK 是异步加载的，此时可能还未加载完成。

解决办法：

SDK 在 __bl 对象上增加了一个 pipe 属性，用于将预调用的信息缓存到此变量中，例如：

__bl.pipe = [
    // 将当前页面的 html 也作为一个 API 上报
    ['api', '/index.html', true, performance.now, 'SUCCESS'],
    
    // SDK 初始化完成后即开启 SPA 自动解析
    ['setConfig', {enableSPA: true}]
];

如果只上报单条数据，也可以直接写成：

__bl.pipe = ['msg', '我是另一个普通的消息'];

其中数组的第 0 个表示方法名，后面依次是入参。 SDK 初始化完成后，就会将预先挂载到 window.__bl.pipe 上的方法及参数依次调用。

注意：在 SDK 初始化完成前，如果多次设置 __bl.pipe 的值，只会以最后一次为准。

另外，pipe 也可以用于 SDK 初始化完成后调用（支持 IE9 及以上），如果不能确定 SDK 是否初始化完成，又不想添加太多的判断逻辑，可以使用此方式

场景：单页面应用中，设置 autoSend: false 后，在应用初始化后上报第一次 PV，此时并不确定 SDK 是否初始化完成

// 设置页面 name 为'homepage'，并且上报 PV
__bl.pipe = ['setPage', 'homepage'];

• npm 引入

场景：

有部分逻辑在调用BrowserLogger.singleton()之前执行，有一些数据想上报

const BrowerLogger = require('@arms/js-sdk');

// 与cdn的pipe结构一致
const pipe = [
    // 将当前页面的 html 也作为一个 API 上报
    ['api', '/index.html', true, performance.now, 'SUCCESS'],
    
    // SDK 初始化完成后即开启 SPA 自动解析
    ['setConfig', {enableSPA: true}]
];

const __bl = BrowserLogger.singleton({pid:'站点唯一ID'},pipe);

小程序

基础类的小程序监控，适用于钉钉、支付宝、微信、字节跳动、百度、京东等各类小程序，并支持Taro，Uniapp等跨端框架构建目标为上述小程序的场景。

参考文档

eapp 微信小程序开发

###1.开始使用

    /**
     * @desc 监控sdk初始化,debug模式仅打印日志，不发送日志
     * 以钉钉中的用法为例
     * monitor.js
     */
    import Logger from '@arms/js-sdk/miniapp';
    module.exports = Logger.singleton({
        debug: true, // 本地开发不发送日志，但打印日志
        pid: 'your-project-id',
        // （可选）基础小程序监控需要手动传入rpc
        sendRequest: (url) => {
            dd.httpRequest({
                url,
                method: 'GET'
            });
        },
        // （可选）拦截不想上报的数据，返回null，undefined，0， false等，会取消本次上报
        beforeReport: (data) => {
            if (data.t === 'api' && data.time > 20000) {
                return
            }
            return data;
        },
        // (可选)需要手动传入获取当前页面路径的方法
        getCurrentPage: () => {
            if (typeof getCurrentPages !== 'undefined' && typeof getCurrentPages === 'function') {
                var pages = (getCurrentPages() || []);
                var pageLength = pages.length;
                var currPage = pages[pageLength - 1];
                return (currPage && currPage.route) || null;
            }
        }
    });
    /**
     * 启动页 app.js
     */
    import logger from './monitor';
    App({
        onLaunch(options) {},
        onShow(options) {},
        onError(msg) {},
    });

2. 通用API

api示例请参考 Getting Started

方法	参数	备注	使用场景举例
setCommonInfo	{[key: string]: string;}	设置日志基础字段	灰度
appLaunch	{}	app launch打点
appShow	{}	app show打点
pageShow	{}	page show打点，发送pv数据
pageHide	{}	page hide打点，发送health数据
error	string	object	错误日志打点

大部分日志上报api见上面的示例即可

3. 说明

小程序系列监控的项目必须符合标准小程序规范: App、Page。 即App层有 onLaunch、onShow、onError; Page层有 onShow、onHide、onUnload。