探针配置(前端)

本文介绍在应用里如何配置和使用集成的天眼探针,包括以下三部分:


探针有哪些配置参数

属性 类型 描述 是否必填 默认值 最低版本(标准探针/小程序)
product_code string 产品编码 2.0.0/1.0.0
app_code string 应用编码 2.0.0/1.0.0
is_spa boolean 是否单页应用 true 2.0.0/1.0.0
page_interval int 检测页面停留的最大时间 1800000 2.0.0/1.0.0
report_logs_threshold object 单次上报日志数量阈值 { Web: 10, 'Hybrid App': 20 } 2.2.3/暂不支持
ignore_pages array 忽略采集的页面 [] 2.1.2/暂不支持
include_search boolean 是否同时上报页面的search参数 false 2.0.4/1.0.0
manual_report_page_load boolean 是否手动上报页面加载时间 false 2.0.0/1.0.0
trace_config object 全链路监控配置 null 2.1.4/暂不支持
report_api_params boolean 是否上报API请求参数 false 2.2.3/暂不支持
api_url_regx string API截取正则 '' 2.0.0/1.0.0
api_ignore_urls array 需要忽略上报API请求的域名 [] 2.0.0/1.0.0
api_property_cb function 自定义加工API事件中上报的API地址的回调方法(标准探针在2.1.2之后移除) null 2.0.0/1.0.0
log_event_attribute string 申明式日志类型收集属性名 'data-event' 2.0.0/1.0.0
log_content_attribute string 申明式日志内容收集属性名 'data-log' 2.0.0/1.0.0
log_module_attribute string 申明式日志模块收集属性名 'data-module' 2.2.7/暂不支持
collect_event_types array 需要采集的日志类型 ['event','page','click','api','error','crash','user-defined'] 2.0.5/1.0.0
tenant_code_query object 自动查询当前租户 { key: '', range: ['url', 'localstorage', 'cookie'] } 2.1.0/1.0.1
user_account_query object 自动查询当前用户名 { key: '', range: ['url', 'localstorage', 'cookie'] } 2.1.0/1.0.1
user_group_query object 自动查询当前用户分组 { key: '', range: ['url', 'localstorage', 'cookie'] } 2.1.0/1.0.1
各参数详细说明与简单示列
product_code(产品编码)

用于区分不同产品上报的数据(产品编码在天眼平台全局唯一),只能由小写英文字符、下划线和数字组成

app_code(应用编码)

用于在同一个产品下区分不同应用上报的数据(应用编码在产品内唯一),只能由小写英文字符、下划线和数字组成

is_spa(是否单页应用)

非单页应用需要将该配置设置为true,避免不必要的window.history修改

page_interval(检测页面停留的最大时间)

单位为毫秒,设置为0时将关闭这个功能,开启时,进入页面后达到该时长后会自动上报一次页面停留事件

report_logs_threshold(单次上报日志数量阈值)

控制单次上报的日志数量阈值,可以按照当前加载的应用形态分别配置

其中Web代表PC Web或Mobile Web形态下配置的阈值,Hybrid App代表混合应用形态下配置的阈值

ignore_pages(忽略采集的页面)

匹配到的页面中的所有事件将不再进行上报,例如使用以下配置初始化后

// 创建探针
const tracker = myWebLogTracker && myWebLogTracker({
  product_code: '产品编码XXX',
  app_code: '应用编码XXX',
  ignore_pages: ['(manage|users)(/[^/]+)+'],
});

探针内部将使用配置参数中的值依次使用new RegExp(ignore_page)进行初始化,并与当前的完整url(document.location.href)进行匹配,在示例中,以下页面或更多其他匹配到的页面中的全部事件将被阻止上报 fast.mypaas.com.cn/manage/product fast.mypaas.com.cn/manage/tracker fast.mypaas.com.cn/users/config

注意:混合应用在集成了MLogCollection插件且配置的collect_event_types中包含crash时,崩溃事件(crash)仍然会照常上报

include_search

控制ps字段(页面地址中的search部分)是否上报

manual_report_page_load(是否手动上报页面加载时间)

如果设置为 true, 则需要在页面加载完成后调用 reportLoaded API 上报,并且原有的page_load事件将不再自动触发

trace_config(全链路监控配置)

开启全链路监控配置包含匹配规则与自定义请求头两部分

// 创建探针
const tracker = myWebLogTracker && myWebLogTracker({
  product_code: '产品编码XXX',
  app_code: '应用编码XXX',
  trace_config: {
    rules: ['fast.mypaas.com.cn'], // 需要使用全链路配置的域名
    headers: [{
      name: 'x-fast-trace-id',  // 请求头名称
      type: 'built-in',         // 请求头类型
      value: 'tid'              // 请求头取值
    }, {
      name: 'x-tenant-code',
      type: 'static',
      value: 'mysoft'
    }]
  },
});

在所有发生的API请求中,仅有符合rules中配置的域名的才会进行添加自定义请求头的操作

自定义请求头的类型分为两种:static(固定值)与built-in(内置值),根据以上示例配置,被添加的请求头如下:

  • x-fast-trace-id: (当前API的tid)
  • x-tenant-code: mysoft

以下为可配置的内置值 | 属性名   | 描述 | | --- | --- | | u | 终端用户唯一标识(根据客户端或设备生成) | | dsw | 设备宽度 | | dsh | 设备高度 | | ua | 浏览器userAgent | | tn | SaaS产品中的租户(名称或编码,推荐使用编码) | | ru | 产品真实用户唯一标识(id或编码,推荐使用编码) | | ug | 用户分组 | | dmf | 设备制造商 | | dmd | 设备型号 | | ac | 应用渠道 | | aid | 应用唯一标识 | | av | 移动应用版本 | | tid | trace_id |

开启了全链路配置后,trace_id会被固定添加到请求头中,无论你是否将其添加到配置(在线配置中tid为固有配置,只能修改请求头名称),未添加tid作为自定义请求头时,将以x-fast-trace-id的请求头名称被强制添加到headers配置

以下事项需要特别注意!!

1、当开启全链路配置后,请求头中会添加设置的请求头,在发生跨域访问时,原本未添加请求头的【简单请求】可能会变为【复杂请求】,从而触发CORS预检(OPTIONS)

2、因可能出现OPTIONS预检请求,接口需要对method为OPTIONS的情况进行处理,避免造成405

关于CORS-preflight的更多可以查看以下文档

1、Access Control CORS 2、CORS-preflight fetch 3、CORS-preflight W3C

report_api_params(是否上报API请求参数)

开启后,将开始采集API事件的请求参数,请求参数将分为url_query_string与request_body两个部分,分别由apirq与apirb两个字段进行上报

参数中可能包含敏感信息(如用户隐私),如需开启参数采集,请对涉及敏感信息的接口进行忽略采集

文件流等类型的参数不采集

如果参数内容较大,开启后可能导致单条日志超过16KB,在参数过大时,会依次舍弃request_body部分和url_query_string部分来保障单条日志长度不超上限

api_url_regx(API截取正则)

推荐用该配置取代api_property_cb,探针内将用配置的字符串使用RegExp构造函数进行初始化为正则表达式对象,并对当前的完整api_url调用match方法进行匹配,先看一个简单的示例

// 对于以下API
const api_1 = 'http://fast.mypaas.com.cn/api/users/profile?t=12345091245581&token=testtesttest';
const api_2 = 'http://fast.mypaas.com.cn/api/product/list?t=12345091245581';
const api_3 = 'http://fast.mypaas.com.cn/api/application/list?t=12345091245581';
// 希望得到/api/users/profile、/api/product/list、/api/application/list 则使用以下配置创建探针
const tracker = myWebLogTracker && myWebLogTracker({
  product_code: '产品编码XXX',
  app_code: '应用编码XXX',
  api_url_regx: 'fast.mypaas.com.cn/api((/[^/]+)+)\?',
});
// 最终得到日志中的API如下
const log_api_1 = '/api/users/profile';
const log_api_2 = '/api/product/list';
const log_api_3 = '/api/application/list';

具体实现原理如下

// 匹配时将用配置创建正则表达式对象
const r = new RegExp('fast.mypaas.com.cn/api((/[^/?]+)+)\?');
// 假设当前的api地址
const current_api_url = 'http://fast.mypaas.com.cn/api/users/profile?t=12345091245581&token=testtesttest';
// 调用字符串的match方法将创建的正则表达式传入
const match_result = current_api_url.match(r);
/*
此处将得到结果数组
  [
    "fast.mypaas.com.cn/api/users/profile",
    "/users/profile",
    "/profile",
    index: 7,
    input: "http://fast.mypaas.com.cn/api/users/profile?t=12345091245581&token=testtesttest",
    groups: undefined
  ]
*/
// 探针将从中按照以下顺序得到结果
const result = match_result ? (match_result[1] || match_result[0] || null) : null;
// 如果result并没有获取到匹配的值 那么探针将按照原有规则将原始url去掉同源domain及search参数部分
const origin_api_url = 'http://fast.mypaas.com.cn/api/users/profile?t=12345091245581&token=testtesttest';

const origin_api_result = '/api/users/profile';

api_ignore_urls

API请求上报开启时有效,支持正则表达式字符串

// 创建探针
const tracker = myWebLogTracker && myWebLogTracker({
  product_code: '产品编码XXX',
  app_code: '应用编码XXX',
  // https://baidu.com/api/xxx/asd          => ignored
  // https://www.google.com/api/xxx/asd     => ignored
  // https://xxxx.xxx.com/api/get?r=google  => ignored
  // https://fast.com/api/data              => ignored
  // http://fast-test.com/api/data          => ignored
  // http://fasta.com/api/data              => not ignored
  api_ignore_urls: ['baidu.com', 'google', '^https?:\/\/fast(-.*)?.com\/api\/(list|data)$']
});

api_property_cb(2.1.2中已移除)

该配置接收一个回调方法作为参数,该方法自动接受完整的API URL作为参数,需要将处理后的API URL字符串返回作为最终数据内的API URL,例如:

// 创建探针
const tracker = myWebLogTracker && myWebLogTracker({
  product_code: '产品编码XXX',
  app_code: '应用编码XXX',
  // https://xxxx.xxxx/api/get_data?t=12345 => https://xxxx.xxxx/api/get_data
  api_property_cb: function(origin_api_url) {
    return origin_api_url.indexOf('?') > -1 ?
      origin_api_url.slice(0, origin_api_url.indexOf('?')) :
      origin_api_url;
  }
});

log_event_attribute 与 log_content_attribute

详细的使用实例可以直接查看最佳实践:上报自定义事件

在HTML标签上增加额外的属性用于替换上报数据中的event字段(缩写:e)、log字段(缩写:l)与module字段(缩写:m)的内容,例如:

在默认配置下:

<div id="page-container" data-module="数据报告">
  <!--此处省略复杂结构-->
  <button data-event="提交报告" data-log="销售数据报告">
    <i class="btn-icon iconfont-add"></i>
    <span class="btn-text">提交</span>
  </button>
  <!--此处省略复杂结构-->
</div>

在点击的这个标签的时候,日志内的数据将包含{ l: '销售数据报告', e: '提交报告', m: '数据报告' }

log_module_attribute的采集是由事件源开始向上层持续查找,直到第一个包含该属性的元素或body为止。

log_module_attribute与log_event_attribute、log_content_attribute所不同的地方在于log_module_attribute所申明的属性不需要另外两个属性处于同一个标签。

如果在初始化中进行如下配置:

// 创建探针
const tracker = myWebLogTracker({
  product_code: '产品编码XXX',
  app_code: '应用编码XXX',
  log_event_attribute: 'data-track',
  log_content_attribute: 'data-content'
});

为了得到相同的结果,则需要修改HTML为:

<button data-track="提交报告" data-content="销售数据报告">提交</button>

collect_event_types

用于定义需要收集的事件类型,默认值为['event','page','click','api','error','crash','user-defined'],代表收集全部类型的事件,如果将其改为[],则表示不收集任何事件

各个值所代表的含义如下:

  • page:页面事件,包含page、page_load、page_stay
  • click:原始点击事件(即未被替换event字段的click事件)
  • api:api事件
  • error:前端错误事件
  • crash:崩溃事件,仅混合APP在集成了MLogCollection插件的情况下有效
  • event:除上述事件以外的探针内置事件,如混合应用的start、resume、pause
  • user-defined:自定义事件,除以上情况以外的其他事件,如:event字段被替换的click事件或用户自行调用接口且type参数未传内置事件名称的情况

tenant_code_query、user_account_query和user_group_query

详细的使用实例可以直接查看最佳实践:在日志中注入真实业务用户信息

用于配置探针自动收集租户编码、用户分组、真实用户数据,这3个配置的格式相同,作用方式相同,区别仅为获取的字段不同,例如

// 创建探针
const tracker = myWebLogTracker && myWebLogTracker({
  product_code: '产品编码XXX',
  app_code: '应用编码XXX',
  // 将在url的search部分搜索key为tenant的取值作为日志中的tenant字段上报
  tenant_code_query: { key: 'tenant', range: ['url'] },
  // 将按照cookie、url的顺序 查找key为account的取值作为日志中的real_user_id字段上报
  user_account_query: { key: 'account', range: ['cookie', 'url'] },
  // 将按照url、cookie的顺序 查找key为role的取值作为日志中的user_group字段上报
  user_group_query: { key: 'role', range: ['url', 'cookie'] }
});

当用户调用过registUser接口方法后,这些配置将失效并永久使用registUser方法写入的数据作为tenant、real_user_id及user_group的值

由于小程序没有cookie只有localStorage,因此配置了range包含cookie的会用localStorage代替(同时配置在localStorage与cookie的,只在localStorage查找一次)


探针提供的API

接口方法

探针在初始化成功后将返回一个实例对象,在浏览器、混合APP环境下,同时也将该实例保存在window.myWebLogTracker,可以通过该实例调用探针提供的接口方法

report(eventName, logInfo, moduleName)

直接上报一条日志数据,使用方式如下:

  window.__myWebLogTracker__ && window.__myWebLogTracker__.report('查看用户信息', {
    report_id: 'xxxx',
    report_name: '运营数据报告'
  }, '数据报告');

上报的日志将包含

{
  e: '查看数据报告',
  m: '数据报告',
  l: { report_id: 'xxxx', report_name: '运营数据报告' }
}

Web探针2.1.2版本之后,report接口不再允许上报与内置事件相同的类型名称了,如仍继续上报同类事件,将在类型前自动添加user-defined-前缀

Web探针2.2.4版本之后,report接口不再允许上报空事件名称,logInfo参数不再要求必填,且不再限定String和Object类型

Web探针2.2.7版本之后,report接口增加了可选参数——moduleName,用于上报事件所属的模块

reportError(Error, extraInfo)

将引发的前端错误手动上报,需要传入一个JS错误对象,可选传入额外数据(String/Object) 例如在接口返回了前端无法处理的异常数据时,在探针中进行上报

  function getProductList(page = 1, keyword = '')
    const params = {
      page_size: 20,
      page,
      keyword
    };
    const response = request('/api/product/list', params);

    if (response.result) {
      return response.data;
    } else {
      // 创建一个Error对象
      const e = new Error(response.msg);
      // 根据需要组织额外信息
      const extraInfo = {
        requestParams: params,
        response
      };
      // 调用探针接口上报异常
      window.__myWebLogTracker__ && window.__myWebLogTracker__.reportError(ErrorObject, extraInfo);

      return response.msg;
    }
});

extraInfo需要探针版本不低于2.2.1,且在集成有MLog插件的混合APP以外的场景下,需要严格控制参数大小,避免日志服务上报整体URL大小超过16Kb(日志服务接口限制)被丢弃

reportLoaded()

手动上报页面加载时间,需要在初始化时将manual_report_page_load配置为true才能使用,否则调用无效

  // 在页面中合适的时机调用该方法(应用内认为页面已经完成加载)
  window.__myWebLogTracker__ && window.__myWebLogTracker__.reportLoaded();
});

由此得到的页面加载时间将为调用时的时间戳(new Date().getTime())减去页面进入时的时间戳

页面进入时的时间戳按照顺序依次获取:performance.timing.navigationStart → 探针JS加载的时间

registUser(realUserInfo)

在获取真实用户信息时,推荐使用真实用户信息读取配置进行真实用户信息的写入,仅当无法使用真实用户信息读取配置时再使用该接口

在调用该方法后,真实用户信息读取配置tenant_code_query、user_account_query和user_group_query将失去作用

该方法可向探针声明当前日志所对应的真实用户信息(含租户编码、真实用户及用户分组)

// 可以在登录后注册
login().then(() => {
  // 使用天眼平台创建的探针对象为 __myWebLogTracker__,手动创建的探针对象调用相应的对象即可
  window.__myWebLogTracker__ && window.__myWebLogTracker__.registUser({
    tenant_code: 'mysoft',
    user_account: 'zhangsan',
    user_group: 'administrator'
  });
});

在此之后同时在下次调用前产生的日志中将包含 { tn: 'mysoft', ru: 'zhangsan', ug: 'administrator' }

继续调用

// 注销
logout().then(() => {
  // 使用天眼平台创建的探针对象为 __myWebLogTracker__,手动创建的探针对象调用相应的对象即可
  window.__myWebLogTracker__ && window.__myWebLogTracker__.registUser({
    tenant_code: 'mysoft',
    user_account: '',
    user_group: ''
  });
});

则之后产生的日志中将包含 { tn: 'mysoft', ru: '', ug: '' }

setBasicInfo(data)

该方法支持向探针中写入两个基础字段,APP热更新版本(app_hotupdate_version,ahv)与自定义通用字段(custom_data,cd)

// 使用天眼平台创建的探针对象为 __myWebLogTracker__,手动创建的探针对象调用相应的对象即可
window.__myWebLogTracker__ && window.__myWebLogTracker__.setBasicInfo({
  // 字段上报为ahv,仅支持字符串
  app_hotupdate_version: '10.1.1001',
  // 字段上报为cd,支持字符串、数组、JSON对象等
  custom_data: {
    system: 'xxx',
    version: 'xxx'
  }
});

在调用之后,上报日志参数的base部分会增加ahv与cd字段和与其对应的值


探针在线配置

管理流程与注意事项

在探针管理的探针配置页中,可以在线实时调整探针的各项配置参数,调整完毕保存后,探针的配置项会直接写入到该应用的专属探针文件中,调整的配置将即时生效

由于探针的配置与初始化均被写入到探针JS文件中,在引入探针后,应用内无需再调用探针初始化,因此也不推荐临时关闭探针在线配置,这将导致由于缺少初始化探针的代码而引发的采集失效

新应用默认开启在线配置,在2019年5月27日前创建的应用默认状态未开启在线配置,需要手动开启

各配置详细说明

日志采集类别

单页应用

上报页面参数

忽略页面地址

手动上报页面加载时间

页面停留有效时间

API截取规则

忽略API列表

全链路配置

申明式自定义事件名称属性

申明式自定义事件日志属性

真实用户信息读取配置

results matching ""

    No results matching ""