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 在创建站点时自动生成。
uid String 用户 ID,用于标识访问用户,可手动配置,用于根据用户 ID 检索。如果不配置,则由 SDK 自动生成且每半年更新一次。
  • Weex 场景:必需
  • 其他场景:非必需
由 SDK 自动生成
tag String 传入的标记,每条日志都会携带该标记。
page String 页面名称。 默认取当前页面 URL 的关键部分:host + pathname
setUsername Function 用于设置一个方法,该方法需要返回类型为 String 的用户名称。 配置后可根据用户名称进行全链路追踪。参见setUsername:设置用户名称方法
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
behavior Boolean 出现错误后进行用户行为回溯。 Browser 默认为 true,小程序默认为 false
c1 String 业务自定义字段,每条日志都会携带该标记。
c2 String 业务自定义字段,每条日志都会携带该标记。
c3 String 业务自定义字段,每条日志都会携带该标记。

setUsername:设置用户名称方法

本配置项用于设置一个方法,该方法需要返回类型为 String 的用户名称。配置后可以根据用户名称进行全链路追踪(会话追踪)、查询用户会话轨迹,便于排查问题。

示例:

// 调用 setConfig 方法修改 SDK 配置项
__bl.setConfig({
    setUsername: function () {
        return "username_xxx";
    }
});            

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 事件完成后才会触发,从而使该配置项会无效。

c1\c2\c3:用户可自定义字段的配置项

:

除了以上列出的配置项,用户可能还需要更多的附加信息辅助处理业务上的问题。因此 ARMS SDK 提供了3个允许用户自定义字段的配置项,用户进行配置后字段内容会携带在每一条上报的日志中。

更多信息