aegis-mp-sdk

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

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

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

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

使用

初始化

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

import Aegis from 'aegis-mp-sdk';

const aegis = new Aegis({
    id: "pGUVFTCZyewxxxxx", // 项目key
    uin: 'xxx', // 用户唯一 ID（可选）
    reportApiSpeed: true // 接口测速
})

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

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

日志上报

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

aegis.info(
  `我是一条白名单上报的信息，只有在白名单中的用户才会上报哟。`
);

aegis.infoAll(
  `我是一条普通的信息，如果上报量很大的话请谨慎使用哟。`
);

aegis.report(
  new Error('我是一条错误信息，推荐在try..catch或者Promise.reject中使用。')
)

aid

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

算法如下:

import { Plugin } from 'aegis-core';

export default new Plugin({
  name: 'aid',
  aid: '',
  init() {
    const env = wx || qq;
    // 某些情况下操作 localStorage 会报错.
    try {
      let aid = env.getStorageSync('AEGIS_ID');
      if (!aid) {
        aid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
          const r = (Math.random() * 16) | 0;
          const v = c === 'x' ? r : (r & 0x3) | 0x8;
          return v.toString(16);
        });
        env.setStorageSync('AEGIS_ID', aid);
      }
      this.aid = aid;
    } catch (e) {}
  },
  onNewAegis(aegis) {
    aegis.bean.aid = this.aid;
  },
});

实例方法

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

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: 777
})

info、infoAll、report

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

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

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

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

reportEvent

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

reportEvent 可以支持两种类型上报参数类型，一种是字符串类型

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

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

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

注意，额外参数的三个 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 的数值计算，如果大于该值，建议进行合理改造。

白名单

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

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

钩子函数

beforeReport

该钩子将会在日志上报前执行，例如：

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  beforeReport(log) {
    // 监听到下面抛出的错误
    console.log(log); // {level: "4", msg: "发生错误啦！！！！"}
  }
});

throw new Error('发生错误啦！！！！');

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

1.level: 日志等级，例如：当 level 为 '4' 时代表错误日志；

2.msg: 日志内容；

全部日志等级如下

{ 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' }

当该钩子返回 false 时，本条日志将不会进行上报，该功能可用来过滤某些不需要上报的错误，例如：

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  beforeReport(log) {
    if (log.level === '4' && log.msg && log.msg.indexOf('碍眼的错误') !== -1) {
      return false
    }
  }
});
throw new Error('碍眼的错误'); // 该错误将不会被上报

上面例子中，当上报的错误内容包含 碍眼的错误 几个关键字时，将不会上报至 RUM 后台中。

onReport

该钩子将在日志上报成功之后执行，用法类似 beforeReport 钩子，唯一不同点在于，该钩子接收到的所有参数都是已经上报完成的日志，而 beforeReport 钩子接收的参数是即将上报的日志。

beforeReportSpeed

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

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  reportApiSpeed: true,
  reportAssetSpeed: true,
  beforeReportSpeed(msg) {
    console.log(msg); // {url: "https://localhost:3001/example.e31bb0bc.js", method: "get", duration: 7.4, status: 200, type: "static"}
    return msg
  }
});

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

1.url: 该资源的请求地址；

2.type: 该资源的类型，目前有 fetch 、 static 两种，当为 fetch 时，Aegis 将会把该资源当成 API 请求进行上报，static 时则视为静态资源；

3.duration: 该资源请求耗时；

4.method: 请求该资源时使用的 http method；

5.status: 服务器返回状态码；

上面的 🌰中，每当 Aegis 收集到一个资源的加载详情时，将会以该资源的加载情况（上面的msg）作为参数调用 beforeReportSpeed 勾子。

如果您配置了该勾子，Aegis 最终的上报内容将以勾子的执行结果为准。例如：

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  reportApiSpeed: true,
  reportAssetSpeed: true,
  beforeReportSpeed(msg) {
    msg.type = 'static';
  }
});

上面的代码中，将所有的 msg.type 设置为 static，这意味着所有的资源都将被当成静态资源进行上报，API 请求也将被报至静态资源中。

使用该勾子，您可以校准 Aegis 类型判断错误的请求。
比方说，假如您有一条接口 https://example.com/api，该接口的响应头 Content-Type 为 text/html， 正常情况下，Aegis 会将该资源当成静态资源进行上报。但在您的业务中，该接口就必须视为 API 请求进行上报，您可以给 Aegis 配置如下勾子进行校正：

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  reportApiSpeed: true,
  reportAssetSpeed: true,
  beforeReportSpeed(msg) {
    if (msg.url === 'https://example.com/api') {
      msg.type = 'fetch';
    }
  }
});

您还可以屏蔽某些资源的测速上报，例如：

const aegis = new Aegis({
  id: 'pGUVFTCZyewxxxxx',
  reportApiSpeed: true,
  reportAssetSpeed: true,
  beforeReportSpeed(msg) {
    // 地址中包含‘https://example.com/api’的都不上报
    if (msg.url.indexOf('https://example.com/api') !== -1) {
      // 返回 ‘false’ 将阻止本条测速日志的上报
      return false
    }
  }
});

错误监控

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

JS执行错误

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

request 请求异常

Aegis 将会改写 wx.request(qq.request) 对象，监听每次接口请求，当 statusCode 大于 400 时将认为该请求是一个失败的请求。

返回码异常

同上，Aegis 在改写 wx.request(qq.request) 对象之后，将获得API返回的内容，并尝试在内容中获取到本次请求的 retcode， 当 retcode 不符合预期的时候，会认为本次请求出现了异常，并进行上报。

如何获取 retcode 以及哪些 retcode 是正常的可以在配置文档中查看。

性能监控

页面测速

Aegis SDK 通过收集小程序的 performance 信息来对您的页面进行测速。

接口测速

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

Aegis 通过劫持 wx.request || qq.request 进行接口测速。

配置文档

示例

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

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

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

new Aegis({
  reportApiSpeed: true, // 需要开两个，不然不会有返回码上报
  reportAssetSpeed: true,
  api: {
    retCodeHandler(data) { 
        // 注意这里拿到的data是string类型，如果需要对象需要手动parse下
      try {
        data = JSON.parse(data)
      } catch(e) {}
      return {
        isErr: data.body.code !== 200 || data.body.retCode !== 0,
        code:  data.body.code
      }
    }
  }
})