参数表格

属性 类型 描述 是否必填 默认值 最低版本(标准探针/小程序)
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查找一次)

results matching ""

    No results matching ""