ARMS 前端监控提供一系列 SDK 配置项,让您能够通过设置参数来满足额外需求,例如忽略指定 URL、API、JS 错误的上报、通过过滤 URL 中的非关键字符使页面聚类、通过随机采样上报来减小上报量并降低负载等。

使用前端监控 SDK 配置项

可通过以下两种方式使用前端监控 SDK 配置项:

  • 向页面插入 BI 探针时在 config 中添加额外参数。

    例如,以下示例代码的 config 中,除了默认的 pid 参数外,还添加了用于单页面应用(Single Page Application)场景的enableSPA 参数。

    <script>
    !(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxxxxx",enableSPA:true};
    with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
    })(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
    </script>
    					
  • 页面初始化完成后,在前端 JS 代码中调用 setConfig 方法来修改配置项,修改方法参见 API 使用指南

SDK 配置项参数

参数 类型 描述 是否必需 默认值
pid String 项目唯一 ID,由 ARMS 在创建站点时自动生成。
tag String 传入的标记,每条日志都会携带该标记。
page String 页面名称。 默认取当前页面 URL 的关键部分:host + pathname
enableSPA Boolean 监听页面的 hashchange 事件并重新上报 PV,适用于单页面应用场景。 false
parseHash Function enableSPA 搭配使用,参见 parseHash:将 URL Hash 解析为 Page 参见 parseHash:将 URL Hash 解析为 Page
disableHook Boolean 禁用 AJAX 请求监听。 false:默认会监听并用于 API 调用成功率上报。
ignoreUrlCase Boolean 忽略 Page URL 大小写。 true:默认忽略。
urlHelper * 代替旧参数 ignoreUrlPath,用于配置 URL 过滤规则,参见 urlHelper:URL 过滤 参见 urlHelper:URL 过滤
apiHelper * 代替旧参数 ignoreApiPath,用于配置 API 过滤规则,参见 apiHelper:API 过滤 参见 apiHelper:API 过滤
parseResponse Function 用于解析自动上报 API 时返回的数据,参见 config.parseResponse:Response 解析方法 参见 config.parseResponse:Response 解析方法
ignore Object 忽略指定 URL/API/JS 错误。符合规则的日志将被忽略且不会被上报,包含子配置项 ignoreUrlsignoreApisignoreErrors,参见 ignore:忽略指定 URL、API、JS 错误 参见 ignore:忽略指定 URL、API、JS 错误
disabled Boolean 禁用日志上报功能。 false
sample Integer 日志采样配置,值为 110100。性能和成功 API 日志按照 1/sample 的比例采样,参见 config.sample:日志采样上报配置 1
sendResource Boolean 上报页面静态资源,参见 sendResource:上报静态资源 false
useFmp Boolean 采集首屏 FMP(First Meaningful Paint,首次有效渲染)数据。 false
enableLinkTrace Boolean 进行前后端链路追踪,参见前后端链路追踪 false
release String 应用版本号。 undefined
environment String 进行前后端链路追踪的环境。 production

parseHash:将 URL Hash 解析为 Page

单页面应用场景中(参见进阶场景),在 enableSPA 设为 true 的前提下,页面触发 hashchange 事件时,parseHash 参数用于将 URL Hash 解析为 Page 字段。

默认值

其默认值由一个简单的字符串处理方法获得:

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

此项一般情况下不需要修改。如果需要在上报时使用自定义的页面名,或者 URL 的 Hash 比较复杂,则需要修改此配置项。例如:

// 定义页面 Hash 和 Page 的映射关系
var PAGE_MAP = {
    '/': '首页',
    '/contact': '联系我们',
    '/list': '数据列表',
    // ...
};
// 页面 load 后调用 SDK 方法
window.addEventListener('load', function (e) {
    // 调用 setConfig 方法修改 SDK 配置项
    __bl.setConfig({
        parseHash: function (hash) {
            key = hash.replace(/\?.*$/, '');
            return PAGE_MAP[key] || '未知页面';
        }
    });
});

urlHelper:URL 过滤

当页面 URL 类似于 http://xxx.com/projects/123456projects 后面的数字是项目 ID)时,如果将xxx.com/projects/123456 作为 page 上报,会导致在数据查看时页面无法聚成一类。这种情况下,为了使同类页面聚类,可以使用 urlHelper 参数过滤掉非关键字符,例如此例中的项目 ID。

注意 用于 URL 过滤规则的旧参数 ignoreUrlPath 现已废弃,请使用新参数 urlHelper。若继续使用旧参数且不使用新参数,配置仍将生效。若同时使用新旧参数,则新参数的配置生效。
说明 此配置项只在自动获取页面 URL 作为 Page 时才会生效。如果手动调用 setPagesetConfig 方法(参考API 使用指南)修改过 Page,或者如果 enableSPA 已设为 true,则此设置项无效。

默认值

此配置项的默认值是以下数组,一般情况下不需要修改。

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

此设置项的默认值会过滤掉 xxxx/123456 后面的数字,例如 xxxx/00001xxxx/00002 都会变成 xxxx/**

值类型

urlHelper 的值可以是以下类型:

  • StringRegExp(正则表达式):将匹配到的字符串去掉。
  • Object<rule, target>:对象包含两个 Key(ruletarget)作为 JS 字符串的 replace 方法的入参。使用方法参见 JS 相关教程中的 String::replace 方法。
  • Function:将原字符串作为入参执行方法,将执行结果作为 Page。
  • Array:用于设置多条规则,每条规则都可以是上述类型之一。

apiHelper:API 过滤

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

注意 用于 API 过滤规则的旧参数 ignoreApiPath 现已废弃,请使用新参数 apiHelper。若继续使用旧参数且不使用新参数,配置仍将生效。若同时使用新旧参数,则新参数的配置生效。

默认值

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

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

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

config.parseResponse:Response 解析方法

该配置项用于解析自动上报 API 时返回的数据。

默认值

该配置项的默认值为:

function (res) {
    if (!res || typeof res !== 'object') return {};
    var code = res.code;
    var msg = res.msg || res.message || res.subMsg || res.errorMsg || res.ret || res.errorResponse || '';
    if (typeof msg === 'object') {
        code = code || msg.code;
        msg = msg.msg || msg.message || msg.info || msg.ret || JSON.stringify(msg);
    }
    return {msg: msg, code: code, success: true};
}                    

以上代码会解析返回的数据,尝试提取出 msgcode。对于一般应用来说,此设置项不需要修改。如果默认值无法满足业务需求,则可以重新设置。

ignore:忽略指定 URL、API、JS 错误

ignore 的值是一个对象,对象中包含 3 个属性:ignoreUrlsignoreApisignoreErrors。可单独设置其中的 1 个或多个属性。

默认值

该配置性的默认值为:

ignore: {
        ignoreUrls: [],
        ignoreApis: [],
        ignoreErrors: []
    },                    

ignoreUrls

ignoreUrls表示忽略某些 URL,符合规则的 URL 下的日志都不会被上报。值可以是StringRegExpFunction或者以上三种类型组成的数组。示例:

__bl.setConfig({
                ignore: {
                    ignoreUrls: [
                    'http://host1/',  // 字符串
                    /.+?host2.+/,     // 正则表达式
                    function(str) {   // 方法
                        if (str && str.indexOf('host3') >= 0) {
                            return true;
                        }
                        return false;
                    }]
                }
            });                    

ignoreApis

ignoreApis 表示忽略某些 API,符合规则的 API 将不会被监控。值可以是StringRegExpFunction或者以上三种类型组成的数组。示例:

__bl.setConfig({
                ignore: {
                    ignoreApis: [
                    'api1','api2','api3', // 字符串
                    /^random/,  // 正则表达式
                    function(str) { // 方法
                        if (str && str.indexOf('api3') >= 0) return true;
                        return false;
                    }]
                }
            });                    

ignoreErrors

ignoreErrors 表示忽略某些 JS 错误,符合规则的 JS 错误不会被上报。值可以是StringRegExpFunction或者以上三种类型组成的数组。示例:

__bl.setConfig({
                ignore: {
                    ignoreErrors: [
                    'test error', // 字符串
                    /^Script error\.?$/, // 正则表达式
                    function(str) { // 方法
                        if (str && str.indexOf('Unkown error') >= 0) return true;
                        return false;
                    }]
                }
            });            

config.sample:日志采样上报配置

为了减小上报量和降低负载,该配置项会对性能和成功 API 日志进行随机采样上报,后台处理日志时会根据对应的采样配置进行还原,因此不会影响 JS 错误和失败 API 等其他类型日志的上报。

采样值 sample 默认为 1,值可以是 110100,对应的采样率为 1/sample,即 1 表示 100% 采样,10 表示 10% 采样,100 表示 1% 采样。

警告 由于是随机采样,如果原上报量较小,该配置项可能会造成较大的统计结果误差,建议仅日均 PV 在 100 万以上的站点使用该配置项。

sendResource:上报静态资源

如果 sendResource 配置为 true,则页面 load 事件触发时会上报当前页面加载的静态资源信息。如果发现页面加载较慢,可以在会话追踪页面查看页面加载的静态资源瀑布图,判断页面加载较慢的具体原因。

sendResource 示例代码:

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxxxxx",sendResource:true};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
</script>            
说明 由于是在页面 load 事件触发时判断,所以请在 config 中配置 sendResource(如以上示例所示),不要使用 setConfig 的方式,因为这种方式可能在页面 load 事件完成后才会触发,从而使该配置项会无效。

更多信息