全部产品
阿里云办公

SDK 配置项

更新时间:2018-12-03 15:31:08

本文介绍了 ARMS 前端监控 SDK 的初始化配置项,说明了如何通过设置不同的参数来应对不同应用场景。

使用方式

在向页面埋入 BI 探针时,可以向 config 中添加额外参数。或者在页面初始化完成之后,在前端 JS 代码中调用setConfig方法(参见 API 使用指南)来修改。

示例

  1. <script>
  2. !(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxxxxx",enableSPA:true};
  3. with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
  4. })(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
  5. </script>

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

配置项参数

参数名 类型 描述 是否必须 默认值
pid String 项目唯一 ID,由 ARMS 在创建站点时自动生成
tag String 传入的标记,每条日志都会携带该标记
page String 页面名称,默认取当前页面 URL 的关键部分 host + pathname
enableSPA Boolean 是否监听页面的 hashchange 事件并重新上报 PV,适用于单页面应用场景 false
parseHash Function 配合 enableSPA 使用,详情见下文 见下文
disableHook Boolean 是否禁用 AJAX 请求监听,默认会监听并用于 API 调用成功率上报 false
ignoreUrlCase Boolean 是否忽略 Page URL 大小写,默认为忽略 true
ignoreUrlPath * URL 过滤规则,详情见下文 见下文
ignoreApiPath * API 过滤规则,详情见下文 见下文
disabled Boolean 禁用日志上报功能 false
parseResponse Function API 自动上报时返回值的解析方法 见下文
sample Integer 日志采样配置,值为 110100。性能和成功API日志按照 1/sample。详情见下文 见下文
sendResource Boolean 是否上报页面静态资源, 详情见下文 false

部分设置项详细说明

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

单页面应用场景中(参见进阶场景介绍),在enableSPA设为true的前提下,页面触发 hashchange 事件时,此参数用于将 URL hash 解析为 page 字段的方法。

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

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

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

示例:

  1. // 定义页面hash和page的映射关系
  2. var PAGE_MAP = {
  3. '/': '首页',
  4. '/contact': '联系我们',
  5. '/list': '数据列表',
  6. // ...
  7. };
  8. // 页面onload后调用SDK方法
  9. window.addEventListener('load', function (e) {
  10. // 调用setConfig方法修改SDK配置项
  11. __bl.setConfig({
  12. parseHash: function (hash) {
  13. key = hash.replace(/\?.*$/, '');
  14. return PAGE_MAP[key] || '未知页面';
  15. }
  16. });
  17. });

2. ignoreUrlPath URL 过滤规则

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

生效场景

此设置项只在自动获取页面 URL 作为 page 时才会生效。如果手动调用setPagesetConfig方法(参见 API 使用指南)修改过 page,或者enableSPA已设为true,则此设置项无效。

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

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

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

ignoreUrlPath 的值可以是以下多种类型,用法分别为:

  • StringRegExp:将匹配到的字符串去掉。关于RegExp请参考正则表达式的语法;
  • Object<rule, target>:对象包含两个 key,分别是 rule 和 target,作为 JS 字符串的replace方法的入参,请参考 JS 相关教程中的String::replace方法;
  • Function:将原字符串作为入参执行方法,将执行结果作为 page;
  • Array:用于设置多条规则,每条子规则都可以是上述类型之一。

3. config.ignoreApiPath API 过滤规则

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

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

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

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

4. config.parseResponse Response 解析方法

该方法用于解析自动上报 API 时返回的数据。默认值为:

  1. function (res) {
  2. if (!res || typeof res !== 'object') return {};
  3. var code = res.code;
  4. var msg = res.msg || res.message || res.subMsg || res.errorMsg || res.ret || res.errorResponse || '';
  5. if (typeof msg === 'object') {
  6. code = code || msg.code;
  7. msg = msg.msg || msg.message || msg.info || msg.ret || JSON.stringify(msg);
  8. }
  9. return {msg: msg, code: code, success: true};
  10. }

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

5. config.sample 抽样上报配置

该配置通过随机抽样上报来减小用户上报量并降低负载。

该配置会对性能成功 API 日志随机抽样上报,后台日志处理会根据对应的抽样配置进行还原,不会影响 JS Error 和失败 API 等其他类型日志的上报

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

由于随机抽样会与实际监控结果有一定误差,建议日均 PV 在 100 万以上的站点采用抽样。

注意:如果用户原上报量较小,该配置可能会造成较大的统计结果误差。

6. sendResource 上报页面加载的静态资源

在页面load时会根据该项配置判断是否要上报页面加载的静态资源,所以请直接使用在config配置sendResource的方式。而setConfig的方式可能在页面load后才会触发,从而配置的sendResource会无效。使用方式如下:

  1. <script>
  2. !(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxxxxx",sendResource:true};
  3. with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
  4. })(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
  5. </script>

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