aegis-mp-sdk

aegis-mp-sdk

Aegis 是腾讯云监控团队提供的前端监控 SDK，涵盖了错误监控，资源测速（img, script, css），接口测速，页面性能（首屏时间）。无需侵入代码，只需引入 SDK 即可自动完成所有监控上报。

在使用 aegis 时无需在业务代码中打点或者做任何其他操作，可以做到与业务代码充分解耦。aegis 将会自动监控前端错误，在错误发生时上报错误的具体情况，帮助您快速定位问题。当您开启资源测速时，aegis 将会自动监听页面资源加载情况（耗费时长、成功率等），并在不影响前端性能的前提下收集前端的性能数据，帮助您快速定位性能短板，提升用户体验。

使用本 SDK 需要配合使用腾讯云前端性能监控 RUM 平台。

aegis-mp-sdk 是针对微信小程序和QQ小程序开发的数据收集和上报 SDK。

使用

安装

在项目支持 NPM 时推荐使用 NPM 安装 Aegis SDK。

$ npm install --save aegis-mp-sdk

初始化

使用非常简单，只需要新建一个 Aegis 实例，传入相应的配置即可：

import Aegis from 'aegis-mp-sdk';

const aegis = new Aegis({
    id: "pGUVFTCZyewxxxxx", // 项目上报ID
    uin: 'xxx', // 用户唯一 ID（可选）
    reportApiSpeed: true, // 接口测速
    reportAssetSpeed: true, // 静态资源测速
    hostUrl: 'https://rumt-zh.com', // 上报域名，中国大陆 rumt-zh.com
    spa: true, // spa 页面需要开启，页面切换的时候上报pv
})

如果使用 ES 模块的方式引入 Aegis 后报错，可以通过如下方式解决

方法一：在 tsconfig.json 中设置 esModuleInterop:true，然后再通过 import Aegis from 'aegis-mp-sdk' 引入

方法二：import * as Aegis from 'aegis-mp-sdk'

方法三：const Aegis = require('aegis-mp-sdk')

::: warning 注意 ⚠️ 为了不遗漏数据，须尽早进行初始化；

aegis-sdk 默认使用 https://aegis.qq.com 作为上报域名，您也可以选择使用 https://rumt-zh.com 作为上报域名。

小程序接入，正式环境需要将上报域名添加到安全域名中。 :::

::: tip 当您做了以上接入工作之后，您已经开始享受 Aegis 提供的以下功能： 1、错误监控：JS执行错误；
2、测速：接口测速；
3、数据统计和分析：可在 RUM 平台 上查看各个纬度的数据分析； :::

日志

Aegis SDK 会主动收集用户的一些性能和错误日志，开发者可以根据不同的参数来配置哪些日志需要上报，以及上报的日志具体信息。

日志类型

全部日志类型如下：

{ logType: 'custom', name: '自定义测速' }
{ logType: 'event', name: '自定义事件' }
{ logType: 'log', name: '日志' }
{ logType: 'performance', name: '页面测速' }
{ logType: 'pv', name: '页面PV' }
{ logType: 'speed', name: '接口和静态资源测速' }
{ logType: 'vitals', name: 'web vitals' }

日志等级

全部日志等级如下：

  { level: 1, name: '白名单日志' },
  { level: 2, name: '一般日志' },
  { level: 4, name: '错误日志' },
  { level: 8, name: 'Promise 错误' },
  { level: 16, name: 'Ajax 请求异常' },
  { level: 32, name: 'JS 加载异常' },
  { level: 64, name: '图片加载异常' },
  { level: 128, name: 'css 加载异常' },
  { level: 256, name: 'console.error' },
  { level: 512, name: '音视频资源异常' }
  { level: 1024, name: 'retcode 异常' }
  { level: 2048, name: 'aegis report' }
  { level: 4096, name: 'PV' }
  { level: 8192, name: '自定义事件' }
  { level: 16384, name: '小程序 页面不存在' }
  { level: 32768, name: 'websocket错误' }
  { level: 65536, name: 'js bridge错误' }
  { level: 131072, name: '小程序异步组件加载失败' }

日志上报

创建完 Aegis 实例之后，就可以开心的上报日志啦 🥰，日志上报同样简单。

// info 可以上报任意字符串，数字，数组，对象，但是只有打开页面的用户在名单中才会上报
aegis.info('test');
aegis.info('test', 123, ['a', 'b', 'c', 1], {a: '123'});


// 也可以上报特定的对象，支持用户传ext参数和trace参数
// 注意这种 case 一定要传 msg 字段
aegis.info({
 msg: 'test',
 ext1: 'ext1',
 ext2: 'ext2',
 ext3: 'ext3',
 trace: 'trace',
});

// 不同于 info，infoAll 表示全量上报
aegis.infoAll({
 msg: 'test',
 ext1: 'ext1',
 ext2: 'ext2',
 ext3: 'ext3',
 trace: 'trace',
});


// error 用来表示 JS 错误日志，也是全量上报，一般用于开发者主动获取JS异常，然后进行上报
aegis.error({
 msg: 'test',
 ext1: 'ext1',
 ext2: 'ext2',
 ext3: 'ext3',
 trace: 'trace',
});
aegis.error(new Error('主动上报一个错误'));

// report 默认是 aegis.report 的日志类型，但是现在你可以传入任何日志类型了
aegis.report({
 msg: '这是一个ajax错误日志',
 level: Aegis.logType.AJAX_ERROR,
 ext1: 'ext1',
 ext2: 'ext2',
 ext3: 'ext3',
 trace: 'trace',
});

info vs infoAll

1. 使用 “infoAll ” 所有用户都上报，方便排查问题。但是也会带来一定的上报和存储成本。
2. 使用 “info” 白名单上报。出了问题，可能会缺少关键路径日志。需要添加白名单，重新操作收集日志（类似于染色系统操作）。

aid

Aegis SDK 为每个用户设备分配的唯一标示，会存储在小程序的 storage 里面，用来区分用户，计算 uv 等。aid 只有用户清理小程序缓存才会更新。

实例方法

Aegis 实例暴露接口简单实用，目前 Aegis 实例有以下方法供您使用： setConfig 、 info 、 infoAll 、 report 、 error 、 reportEvent 、 reportTime 、 time 、 timeEnd、 destroy

setConfig

该方法用来修改实例配置，比如下面场景：

• 在实例化 Aegis 时需要传入配置对象。

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  uin: '777'
})

• 很多情况下，并不能一开始就获取到用户的 uin，而等获取到用户的 uin 才开始实例化 Aegis，如果这期间发生了错误 Aegis 将监听不到。uin 的设置可以在获取到用户的时候：

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx'
})

// 拿到uin之后...
aegis.setConfig({
  uin: '888'
})

info、infoAll、report

这三个方法是 Aegis 提供的主要上报手段。

aegis.info('上报一条白名单日志，这两种情况这条日志才会报到后台：1、打开页面的用户在名单中；2、对应的页面发生了错误🤨');

aegis.infoAll('上报了一条日志，该上报与info唯一的不同就在于，所有用户都会上报');

aegis.report(new Error('上报一个错误'));

reportEvent

该方法可用来上报自定义事件，平台将会自动统计上报事件的各项指标，诸如：PV、UV、平台分布等...

reportEvent 可以支持两种类型上报参数类型。

1. 字符串类型

aegis.reportEvent('XXX请求成功');

1. 对象类型，ext1 ext2 ext3 默认使用 new Aegis 的时候传入的参数，自定义事件上报的时候，可以覆盖默认值。

aegis.reportEvent({
  name: 'XXX请求成功',
  ext1: '额外参数1',
  ext2: '额外参数2',
  ext3: '额外参数3',
})

::: warning 注意 额外参数的三个 key 是固定的，目前只支持 ext1、 ext2、 ext3。 :::

reportTime

该方法可用来上报自定义测速，例如：

// 假如‘onload’的时间是1s
aegis.reportTime('onload', 1000);

或者如果需要使用额外参数，可以传入对象类型参数，ext1，ext2，ext3 会覆盖默认值：

aegis.reportTime({
  name: 'onload', // 自定义测速 name
  duration: 1000, // 自定义测速耗时(0 - 60000)
  ext1: 'test1',
  ext2: 'test2',
  ext3: 'test3',
});

onload 可以修改为其他的命名。

time、timeEnd

该方法同样可用来上报自定义测速，适用于两个时间点之间时长的计算并上报，例如：

aegis.time('complexOperation');
/**
 * .
 * .
 * 做了很久的复杂操作之后。。。
 * .
 * .
 */
aegis.timeEnd('complexOperation'); /** 此时日志已经报上去了😄**/

complexOperation 同样可以修改为其他的命名。 自定义测速是用户上报任意值，服务端对其进行统计和计算，因为服务端不能做脏数据处理，因此建议用户在上报端进行统计值限制，防止脏数据对整体产生影响。 目前 Aegis 只支持 0-60000 的数值计算，如果大于该值，建议进行合理改造。 高频率的自定义测速上报尽量使用 reportTime。time 和 timeEnd 上报会存在上报值覆盖的问题。比如 aegis.time(aaa), 在调用 aegis.timeEnd(aaa) 之前，又调用了一次 aegis.time(aaa), 则上报的时间为 timeEnd 时间 - 第二次 time 的时间。

destroy

该方法用于销毁 sdk 实例，销毁后，不再进行数据上报

aegis.destroy();

白名单

白名单功能是适用于开发者希望对某些特定的用户上报更多的日志，但是又不希望太多上报来影响到全部日志数据，并且减少用户的接口请求次数，因为 TAM 设定了白名单的逻辑。

1. 白名单用户会上报全部的 API 请求信息，包括接口请求和请求结果。
2. 白名单用户可以使用 info 接口信息数据上报。
3. info vs infoAll：在开发者实际体验过程中，白名单用户可以添加更多的日志，并且使用 info 进行上报。infoAll 会对所有用户无差别进行上报，因此可能导致日志量上报巨大。
4. 通过接口 whitelist 来判断当前用户是否是白名单用户，白名单用户的返回结果会绑定在 aegis 实例上 (aegis.isWhiteList) 用来给开发者使用。
5. 用了减少开发者使用负担，白名单用户是团队有效，可以在 应用管理-白名单管理 内创建白名单，则团队下全部项目都生效。

钩子函数

beforeRequest

该钩子将会在日志上报前执行，用于对上报数据的拦截和修改，通过返回不同类型的值：

• 拦截：返回false
• 修改：修改入参的值并返回

const aegis = new Aegis({
  id: "pGUVFTCZyewxxxxx",
  beforeRequest: function(data) {
    // 入参 data 的数据结构：{logs: {…}, logType: "log"}
    if (data.logType === 'log' && data.logs.msg.indexOf('otheve.beacon.qq.com') > -1) {
      // 拦截：日志类型为 log，且内容包含 otheve.beacon.qq.com 的请求
      return false;
    }
    // 入参 data 数据结构：{logs: {}, logType: "speed"}
    if (data.logType === 'speed' && data.logs.url.indexOf('otheve.beacon.qq.com') > -1) {
      // 拦截：日志类型为 speed，并且接口 url 包含 otheve.beacon.qq.com 的请求
      return false;
    }
    if (data.logType === 'performance') {
      // 修改：将性能数据的首屏渲染时间改为2s
      data.logs.firstScreenTiming = 2000;
    }
    return data;
  }
});

其中，msg 将会有以下几个字段：

1.logs: 上报的日志内容;

2.logType: 日志类型

logType等于custom时，logs的值如下：

{name: "白屏时间", duration: 3015.7000000178814, ext1: '', ext2: '', ext3: '', from: ''}

logType等于event时，logs的值如下：

{name: "ios", ext1: "", ext2: "", ext3: ""}

logType等于log时，logs的值如下：

{ level: '1', msg: '接口请求日志（白名单日志）' } // 具体level信息参考日志等级

logType等于performance时，logs的值如下：

{contentDownload: 2, dnsLookup: 0, domParse: 501, firstScreenTiming: 2315, resourceDownload: 2660, ssl: 4, tcp: 4, ttfb: 5}

logType等于speed时，logs的值如下：

// 静态资源
{connectTime: 0, domainLookup: 0, duration: 508.2, nextHopProtocol: "", isHttps: true, method: "get", status: 200, type: "static", url: "https://puui.qpic.cn/xxx", urlQuery: "max_age=1296000"}

// API
{duration: 26, isErr: 0, isHttps: true, method: "GET", nextHopProtocol: "", ret: "0", status: 200, type: "fetch", url: "https://xx.com/cgi-bin/whoami"}

logType等于vitals时，logs的值如下：

{CLS: 3.365504747991234, FCP: 139.39999997615814, FID: -1, LCP: 127.899}

modifyRequest

该钩子函数会在所有请求发出前调用，参数中会传入请求的所有内容，必须返回待发送内容。

function changeURLArg(url,arg,arg_val) {
  var pattern=arg+' = ([^&]*)';
  var replaceText = arg+'='+arg_val;
  if (url.match(pattern)) {
    var tmp = '/('+ arg+'=)([^&]*)/gi';
    tmp = url.replace(eval(tmp),replaceText);
    return tmp;
  }
  return url;
}
const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  modifyRequest(options) {
    if (options.type === 'performance') {
      // 页面测速，此时可以修改options内容，如修改页面测速platform
      options.url = changeURLArg(options.url, 'platform', type)
    }
    return options
  }
});

afterRequest

该勾子将会在数据上报后被执行，例如：

const aegis = new Aegis({
  id: "pGUVFTCZyewxxxxx",
  reportApiSpeed: true,
  reportAssetSpeed: true,
  afterRequest: function(msg) {
    // {isErr: false, result: Array(1), logType: "log", logs: Array(4)}
    console.log(msg);
  }
});

其中，msg 将会有以下几个字段：

1.isErr: 请求上报接口是否错误；

2.result: 上报接口的返回结果；

3.logs: 上报的日志内容;

4.logType: 日志类型，有以下值speed：接口和静态资源测速，performance：页面测速，vitals：web vitals，event：自定义事件，custom：自定义测速;

错误监控

::: warning Aegis 的实例会自动进行以下监控，注意！是 Aegis 实例会进行监控，当您只是引入了 SDK 而没有将其实例化时，Aegis 将什么都不会做。 :::

JS执行错误

Aegis 通过监听 window 对象上的 onerror 事件来获取项目中的报错，并且通过解析错误和分析堆栈，将错误信息自动上报到后台服务中。该上报的上报等级为 error ，所以，当自动上报的错误达到阈值时，Aegis 将会自动告警，帮助您尽早发现异常。由于上报等级为 error ，自动上报也将影响项目的每日评分。

request 请求异常

Aegis 将会改写 wx.request(qq.request) 对象（请您放心，Aegis很专业），监听每次接口请求，当 statusCode 不存在或者大于等于 400 时认为该请求是一个失败的请求，亦或是接口超时，abort 和其他类型的失败。

注意： Aegis SDK 在错误发生的时候，不会主动收集接口请求参数和返回信息，如果需要对进口信息进行上报，可以使用 api 参数里面的 apiDetail 进行开启。

new Aegis({
  id: '',
  api: {
    apiDetail: true,
  },
});

retcode异常

同上，Aegis 在改写 wx.request(qq.request) 对象之后，将获得API返回的内容，并尝试在内容中获取到本次请求的 retcode。

retcode 的值会从用户返回 response body 的第一层（如果第一层取不到，再取第二层）的 code、ret、retcode、errcode 中获取。 Aegis 默认 retcode 的值为0是正常的，非0都是异常的。当 retcode 发生异常的时候，会上报一个 retcode异常的日志。 用户可以通过 api.retCodeHandler 对这个值和是否异常进行修正。

websocket异常

Aegis默认不会对全局websocket对象进行重写，默认不会监控websocket相关错误，如果需要打开相关功能可以在创建Aegis对象时设置websocketHack: true。

new Aegis({
  id: '',
  websocketHack: true
});

性能监控

页面性能

Aegis 小程序 SDK 会自动收集页面性能数据并上报。包括：

1. 程序启动时间
2. 代码注入时间
3. 页面首次渲染时间
4. 路由切换时间

::: warning 注意 ⚠️ 获取页面性能数据依赖小程序的 Performance API，请保证基础库版本 >2.11.0。 手Q小程序目前暂时不支持 Performance API，所以不会上报页面性能数据。 :::

组件更新性能(setData)

Aegis 小程序 SDK 默认会自动获取组件的更新性能数据并上报，便于对组件针对性优化。

::: warning 注意 ⚠️ 获取更新性能统计信息依赖小程序框架提供的API setUpdatePerformanceListener，请保证基础库版本 >2.12.0。 详情可以参考这里。 :::

::: warning 注： 某些应用场景下的小程序项目可能数据更新很频繁从而导致上报请求过多，因此 sdk 针对 setData 数据上报提供了额外的配置项，具体可见下方配置文档中的setDataReportConfig配置项。 :::

接口测速

打开方式：初始化时传入配置 reportApiSpeed: true

Aegis 通过劫持 wx.request || qq.request 进行接口测速，具体代码在 这里

小游戏

aegis-mp-sdk 在微信小游戏中的用法跟小程序中的用法基本一样，但是由于小游戏目前不支持 Performance.createObserver ，所以目前有以下几个区别

1. 小游戏中不支持 loadPackage 耗时和大小的上报
2. 小游戏中不支持页面性能 performance 数据上报
3. 小游戏中不支持静态资源数据上报

配置文档

配置	描述
id	必须，string，默认 无。 开发者平台分配的项目上报ID
uin	建议，string 业务定义的当前用户的唯一标识符，用来查找固定用户的日志。白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持字母数字@=._-，正则表达式: /^[@=.0-9a-zA-Z_-]{1,60}$/
onError	可选，boolean，默认 true。 当前实例是否需要进行错误监听，获取错误日志
reportApiSpeed	可选，boolean，默认 false。 是否开启接口测速
reportAssetSpeed	可选，boolean，默认 false。 是否开启静态资源测速
reportLoadPackageSpeed	可选，boolean，默认 true。 是否开启包下载耗时上报
pagePerformance	可选，boolean 默认 true。 是否开启页面测速
version	可选，string，默认 sdk 版本号。 当前上报版本，当页面使用了pwa或者存在离线包时，可用来判断当前的上报是来自哪一个版本的代码，仅支持字母数字.,:_-，长度在 60 位以内 /^[0-9a-zA-Z.,:_-]{1,60}$/
delay	可选，number，默认 1000 ms。 上报节流时间，在该时间段内的上报将会合并到一个上报请求中。
repeat	可选，number，默认 5。 重复上报次数，对于同一个错误或者同一个接口测速超过多少次不上报。如果传入 repeat 参数为 0，则不限制。
env	可选，enum，默认 Aegis.environment.production。 当前项目运行所处的环境。｜
spa	可选，boolean，默认 false。 当前页面是否是单页应用？true的话将会监听hashchange及history api，在页面跳转时进行pv上报
pageUrl	可选，string，默认是小程序 getCurrentPages。 修改上报数据中页面地址，开发者可以主动对数据进行聚合和降低维度｜
urlHandler	可选，Function。 动态修改上报数据中页面地址 from，可以配合 pageUrl 参数使用｜
websocketHack	可选，boolean，默认 false 是否开启websocket监控。
enableHttp2	可选，boolean，默认 false。 上报数据是否支持 HTTP2，默认没有开启。
hostUrl	可选，默认是 https://aegis.qq.com。 影响全部上报数据的 host 地址，下面几个 url 地址设置后会覆盖对应的上报地址 ｜
url	可选，string，默认 'https://aegis.qq.com/collect'。 日志上报地址
pvUrl	可选，string, 默认 'https://aegis.qq.com/collect/pv' pv 上报地址 ｜
whiteListUrl	可选，string，默认 'https://aegis.qq.com/collect/whitelist'。 白名单确认接口 如果想要关闭白名单接口请求，可以传空字符串
offlineUrl	可选，string，默认 'https://aegis.qq.com/collect/offline'。 离线日志上报地址
eventUrl	可选，string，默认 'https://aegis.qq.com/collect/events'。 自定义事件上报地址
speedUrl	可选，string，默认 'https://aegis.qq.com/speed'。 测速日志上报地址
customTimeUrl	可选，string，默认 'https://aegis.qq.com/speed/custom'。 自定义测速上报地址
performanceUrl	可选，string，默认 'https://aegis.qq.com/speed/performance'。 页面性能日志上报地址
setDataReportConfig	可选，object，默认为{}。相关的配置: disabled: 可选，Boolean，默认false。是否禁用setData数据上报; timeThreshold: 可选，Number，单位为ms，默认值为30。上报的耗时阈值，表示仅上报更新耗时超过该阈值的数据； withDataPaths: 可选，Boolean，默认为true。是否上报本次更新的字段信息；
api	可选，object，默认为 {}。相关的配置: apiDetail : 可选，boolean，默认false。上报 api 信息的时候，是否上报 api 的请求参数和返回值; retCodeHandler: Function(data: String, url: String, xhr: Object):{isErr: boolean, code: string}， 返回码上报钩子函数。 会传入接口返回数据,请求url和xhr对象; reqParamHandler: Function(data: any, url: String) 上报请求参数的处理函数，可以对接口的请求参数进行处理，方便用户过滤上报请求参数的信息; resBodyHandler: Function(data: any, url: String) 上报 response 返回 body 的处理函数，可以对接口返回值的 response body 进行处理，只上报关键信息; reqHeaders: Array 需要上报的 http 请求 request headers 列表。 resHeaders: Array 需要上报的 http 请求 response headers 列表。注意使用小写。 resourceTypeHandler: Function，请求资源类型修正钩子函数 会传入接口url，返回值为‘static’或‘fetch’。见示例[1] reportRequest: boolean, 默认为false。 开启aegis.info全量上报, 不需要白名单配置。并上报所有接口请求信息（请开启reportApiSpeed） injectTraceHeader: 可选，string，且必须为枚举值 'traceparent', 'sw8', 'b3', 'sentry-trace' 中的一种，开启该参数后，Aegis 会在用户请求头中注入相关 trace header。 injectTraceUrls: 可选，Array, 数组中传入 string 或者 RegExp。标记哪些请求 url 需要注入 trace 请求头。 injectTraceIgnoreUrls: 可选，Array, 数组中传入 string 或者 RegExp。标记哪些请求 url 不需要注入 trace 请求头。
ext1	可选，string，自定义上报的额外维度，上报的时候可以被覆盖
ext2	可选，string，自定义上报的额外维度，上报的时候可以被覆盖
ext3	可选，string，自定义上报的额外维度，上报的时候可以被覆盖

示例

[1] retCodeHandler，假如后台返回数据为:

{
  body: {
    code: 200,
    retCode: 0,
    data: {
      // xxx
    }
  }
}

业务需要：code不为200，或者retCode不为0，此次请求就是错误的。此时只需进行以下配置：

new Aegis({
  // xxx
  reportApiSpeed: true, // 需要开启，不然不会有返回码上报
  reportAssetSpeed: true,
  api: {
    retCodeHandler(data) {
      // 注意这里的data的数据类型，跟接口返回值的数据类型一致，开发者需要根据实际情况自行处理
      try {
        data = JSON.parse(data)
      } catch(e) {}
      return {
        isErr: data.body.code !== 200 || data.body.retCode !== 0,
        code:  data.body.code
      }
    }
  }
})