SDK参考

本页索引

pid | uid | tag | page | setUsername | enableSPA | parseHash | disableHook | ignoreUrlCase | urlHelper | apiHelper | parseResponse | ignore | disabled | sample | pvSample | sendResource | useFmp | enableLinkTrace | release | environment | behavior | c1\c2\c3 | autoSendPerf

如何使用前端监控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方法来修改配置项。

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

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

pid

[回到顶部]

uid

示例：调用setConfig方法修改SDK配置项。

__bl.setConfig({
    uid: 12345
});        

[回到顶部]

tag

[回到顶部]

page

[回到顶部]

setUsername

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

示例：调用setConfig方法修改SDK配置项。

__bl.setConfig({
    setUsername: function () {
        return "username_xxx";
    }
});            

[回到顶部]

enableSPA

[回到顶部]

parseHash

单页面应用场景中（参见SPA页面上报），在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] || '未知页面';
        }
    });
});

[回到顶部]

disableHook

[回到顶部]

ignoreUrlCase

[回到顶部]

urlHelper

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

默认值

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

[
    // 将所有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字符串的replace方法的入参。使用方法参见JS相关教程中的String::replace方法。

• Function：将原字符串作为入参执行方法，将执行结果作为Page。

• Array：用于设置多条规则，每条规则都可以是上述类型之一。

[回到顶部]

apiHelper

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

默认值

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

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

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

如果需要在API中上报?后面的参数，例如：https://arms.console.aliyun.com/apm?pid=fr6fbgbeot中的pid参数，需要按照以下方法手动上报API数据：

• 使用ignore方法，关闭自动上报。具体操作，请参见ignore。

• 使用api()自行上报API数据。具体操作，请参见api()。

[回到顶部]

parseResponse

该配置项用于解析自动上报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};
}                    

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

[回到顶部]

ignore

ignore的值是一个对象，对象中包含4个属性：ignoreUrls、ignoreApis、ignoreErrors和ignoreResErrors。可单独设置其中的1个或多个属性。

默认值

该配置项的默认值为：

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

ignoreUrls

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

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

ignoreApis

ignoreApis表示忽略某些API，符合规则的API将不会被监控。值可以是String、RegExp、Function或者以上三种类型组成的数组。示例：

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

ignoreErrors

ignoreErrors表示忽略某些JS错误，符合规则的JS错误不会被上报。值可以是String、RegExp、Function或者以上三种类型组成的数组。示例：

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

ignoreResErrors

ignoreResErrors表示忽略指定的资源错误，符合规则的资源错误不会被上报。值可以是String、RegExp、Function或者以上三种类型组成的数组。示例：

__bl.setConfig({
                ignore: {
                    ignoreResErrors: [
                    'http://xx/picture.jpg', // 字符串
                    /jpg$/, // 正则表达式
                    function(str) { // 方法
                        if (str && str.indexOf('xx.jpg') >= 0) return true;   // 不上报
                        return false;   // 上报
                    }]
                }
            });

[回到顶部]

disabled

[回到顶部]

sample

sample配置项作用：

• 减小API的数据上报量（降低部分费用），更精确的方案建议使用ignore参数过滤掉某些不需要监控的API数据，更多信息，请参考ignore。

• 降低采集数据的性能开销。

sample配置项说明：

• 为了减小上报量和降低负载，该配置项会对性能和成功API日志进行随机采样上报，后台处理日志时会根据对应的采样配置进行还原，因此不会影响JS错误率和失败API率等指标的计算。但是会导致在查询API详情或者相关数据明细的时候，无法保证一定可以查看明细。

• 采样值sample默认为1，值可以是1~100的整数，对应的采样率为1/sample，例如：1表示100%采样，10表示10%采样，100表示1%采样。

[回到顶部]

pvSample

pvSample配置项作用：

• 减小PV的数据上报量（降低部分费用）。

• 降低采集数据的性能开销。

pvSample配置项说明：

• 为了减小上报量和降低负载，该配置项会对PV日志进行随机采样上报，后台处理日志时会根据对应的采样配置进行还原，样本量足够大的情况下对JS错误率等指标的计算影响不大。

• 采样值pvSample默认为1，值可以是1~100的整数，对应的采样率为1/pvSample，例如：1表示100%采样，10表示10%采样，100表示1%采样。

[回到顶部]

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>            

[回到顶部]

useFmp

[回到顶部]

enableLinkTrace

[回到顶部]

release

[回到顶部]

environment

[回到顶部]

behavior

[回到顶部]

autoSendPerf

[回到顶部]

c1\c2\c3

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

[回到顶部]