miniapp-reporter

    1.4.4 • Public • Published

    如何接入小程序监控SDK

    1. 支持情况

    • [√] 支付宝小程序
    • [√] 微信小程序
    • [√] 钉钉小程序(内置于 APPX中,用户只需在开放平台接入稳定性监控即可,不需要再引入SDK)
    • [√] 百度智能小程序
    • [√] 头条小程序

    2. 设置安全域名

    在小程序开发者后台,将 https://px.effirst.com 添加到 Request 合法域名
    务必设置安全域名、设置安全域名、设置安全域名,重要的事情讲三遍,否则所有数据无法上报!!!

    3. 引用方式

    3.1 npm包(推荐)

    // 1. 安装依赖
    npm i miniapp-reporter --save
    
    // 2. 引入,目前支持 支付宝小程序(alipay)、微信小程序(wechat)、钉钉小程序(dd)、百度小程序(baidu)、头条小程序(tt)
    import AliPayReporter from 'miniapp-reporter/alipay'
    import WechatReporter from 'miniapp-reporter/wechat'
    import DDReporter from 'miniapp-reporter/dingtalk'
    import BaiduReporter from 'miniapp-reporter/baidu'
    import TTReporter from 'miniapp-reporter/tt'

    3.2 源码依赖

    目前大部分小程序都已经支持 npm了,所以首推 npm依赖的方式来使用SDK
    当然,有些平台对npm的支持略显特殊,如果发现安装依赖后无法编译,那么可以尝试用源码依赖的方式来解决

    // 如何获取代码 
    // 1. 从 node_modules/miniapp_reporter 目录下拷贝代码到小程序的项目目录下
    // 或 2. 从 cdn上下载:地址待公布
    
    举栗:微信小程序项目 wechatDemo 源码依赖SDK
    1. 获取代码 wechat.js
    2. 拷贝 wechat.js 至项目目录中,比如 wechatDemo/utils
    |- wechatDemo
    |----utils
    |------wechat.js
    
    注:SDK的构建产物支持直接用ES6语法来 import,也可以 require

    4 如何使用

    4.1 创建应用

    登录 https://yueying.effirst.com/#/app/add?type=mapp 选择小程序类型、应用名称、及应用描述,之后点击创建应用即可

    4.2 初始化

    一般情况下,我们初始化一次SDK即可,可以把SDK实例导出供全局复用

    1. 确保已按照「步骤3:引用方式」正确安装依赖(这里以 npm依赖为例)
      2. 在 utils目录下,新增 miniapp-reporter.js 文件,文件加入以下内容
    // miniapp-reporter.js
    
    import MiniAppReporter from 'miniapp-reporter/alipay'
    const itraceInstance = MiniAppReporter.getInstance({
      bid: 'your bid', // 应用标识,必填,从「步骤4.1:创建应用」获取
      uid: '', // 用户标识,非必须,默认是 uuid,建议设置;支持函数
      rel: ''  // 小程序版本,非必须,默认为空,建议设置;支持函数
    //  rel: function () { xxxx }
    })
    
    // 导出单例
    export default itraceInstance
    
    注:微信小程序,只需要将导入的包换为wechat即可:'miniapp-reporter/wechat'

    4.3 全局监听

    全局监听主要是针对 app.js,这一步可以实现对 **全局异常 **以及 **API请求 **的监控

    // 根目录下的 app.js
    
    import itrace from '/utils/miniapp-reporter';
    
    App(
      itrace.wrapApp({   
        onLaunch () {},
        onShow () {},
        onHide () {},
        onError (error) {}
      })
    );
    
    // itrace.wrapApp 的参数与原App的参数保持一致
    // 因此,这一步变动,仅仅只把原来App的入参用 itrace.wrapApp() 来包裹一层,使用成本较低

    4.4 页面监听

    目前主要是监听页面PV

    // 某页面的入口js
    
    import itrace from '/utils/miniapp-reporter';
    
    const app = getApp();
    
    Page(
      itrace.wrapPage({
        data: {},
        onLoad() {},
        onShow() {},
        onHide () {},
        onUnload () {},
        onReady () {} , 
        onTodoChanged(e) {},
        addTodo() {}
      })
    );
    
    // 显然,这里的调用方式跟 app.js是一样的

    5 进阶

    5.1 手动上报

    除了常规的 PV/UV、JSError、API请求监控之外,我们还提供了强大的自定义上报功能 结合iTrace Web平台的聚合分析功能,用户可以轻易做到对各种场景的监控分析

    // 前置条件,引入 itrace实例
    // 任意页面的 JS
    import itrace from '/utils/miniapp-reporter';

    5.1.1 通用的手动上报接口 report

    // logData为一个Object类型的参数
    itrace.report(logData)
    • logData的通用字段:
    {
    	category: 100, // [必须] 指定监控项,0-99 为系统预留
      msg: '',       // [必须] 一段自定义的字符串
      c1: '',        // [必须] 预留的扩展字段1,即上报的日志可以带上该属性用于聚合分析;下同
      c2: '',        // [必须] 预留的扩展字段2
      c3: '',        // [必须] 预留的扩展字段3
      c4: '',        // [必须] 预留的扩展字段4
      c5: '',        // [必须] 预留的扩展字段5
     	w_succ: 1,     // [可选] 用于计算率的标识,可选为 1  0
      wl_avgv1: 100, // [可选] 用于监控如耗时,性能等均值,必须是一个数字
    }

    5.1.2 SDK内置的 API

    * 手动上报 JS异常 reportJSError

    itrace.reportJSError(error, logData) // 等价于 itrace.reportError

    参数说明

    * 手动上报 api数据

    itrace.reportApi(logData) // 等价于 itrace.reportApiError

    **
    logData字段如下:

    {
      url: '',         // 建议是完整请求地址,包括协议, https://your.gateway.domain/api/user
      method: '',      // HTTP请求方法,GET、POST、PUT、DELETE等
      queryString: '', // 支持字符串或者 Object格式:p1=v1&p2=v2 or { p1: v1, p2: v2 }
      headers: {},     // 请求头,Object格式
      body: '',        // 请求内容
      response: '',    // 响应内容
      respHeaders: {}, // 响应头
      status: 200,     // HTTP响应码
      spent: 100       // 请求RT:整数,默认单位毫秒
    }

     

    5.2 其他

    能阅读到此处的用户,说明默认的 SDK配置已经无法满足你了。实际上,这一小节的内容正是介绍 SDK的各种灵活配置的。

    5.2.1 采样率设置

    日志量较大的情况下,建议配置一定采样率,避免日志全量上报

    // 1. 全局,默认采样率是 1(100%)
    const itraceInstance = MiniAppReporter.getInstance({
    //  ...
      sampleRate: 0.5 // 或者 50%,所有日志类型都会应用此采样率
    //  ...
    })
    
    // 2.单独对 JSError进行采样
    const itraceInstance = MiniAppReporter.getInstance({
    //  ...
      jsErrorSampleRate: 0.5 // 或者 50%,JS异常日志都会应用此采样率
    //  ...
    })
    
    // 3.单独对 api进行采样
    const itraceInstance = MiniAppReporter.getInstance({
    //  ...
      apiSampleRate: 0.5 // 或者 50%,api请求日志都会应用此采样率
    //  ...
    })
    // 4.单独对 性能 进行采样
    const itraceInstance = MiniAppReporter.getInstance({
    //  ...
      launchPerfSampleRate: 0.5, // 或者 50%,启动性能日志都会应用此采样率
      pagePerfSampleRate: 0.5 // 或者 50%,页面性能日志都会应用此采样率
    //  ...
    })

    5.2.2 全局日志过滤

    所有日志上报时都会应用此过滤器

    const itraceInstance = MiniAppReporter.getInstance({
    //  ...
      beforeSend: function (logData) {
      	// logData格式参考 4.1.1章节
        // 有需要的用户,在这里可以对 logData进行加工
        
        // 如果要阻止本条日志上报,可以
        // return false
      }
    //  ...
    })

    5.2.3 JSError过滤

    可能在部分场景下,我们并不关注某些类型的JS异常,此时就可以使用该过滤器

    const itraceInstance = MiniAppReporter.getInstance({
    //  ...
      jsErrorFilter: function (error) {
      	// error为一个标准的 JS Error对象
        
        // 如果要阻止本条日志上报,可以
        // return false
      }
    //  ...
    })

    5.2.4 API相关

    SDK 默认会开启 API监控的功能,同时由于安全方面的考虑,SDK默认并不会上报请求体、请求头、响应体以及响应头,但这些默认行为,你都有机会来自定义

    const itraceInstance = MiniAppReporter.getInstance({
    //  ...
      disableApi: true,         // 关闭 api监控
      apiBody: false,           // 上报请求体,默认 false,不上报
      apiResponse: false,       // 上报响应体,默认 false,不上报
      apiRequestHeader: false,  // 上报请求头,默认 false,不上报
      apiResponseHeader: false, // 上报响应头,默认 false,不上报
      apiFilter: function (logData) {
    	// ...
      	// logData的格式参考 「手动上报 api数据」小节
        // return false 可阻止本条日志上报
      // ...
    	}
    //  ...
    })
    
    

    5.2.5 性能相关

    配置

    const itraceInstance = MiniAppReporter.getInstance({
    //  ...
      launchPerfSampleRate: 0.5, // 或者 50%,启动性能日志都会应用此采样率
      pagePerfSampleRate: 0.5, // 或者 50%,页面性能日志都会应用此采样率
      disableLaunchPerf: true,// 关闭 启动性能 监控
      disablePagePerf: true,// 关闭 页面性能 监控
      //性能日志默认将在 onReady 钩子回调 5000ms后或onHide/onUnload钩子回调时上报
      perfUploadAfter: 5000,
      launchPerfFilter: function (logData) {
    	// ...
        // return false 可阻止本条日志上报
      // ...
    	}
      pagePerfFilter: function (logData) {
    		// return false 可阻止本条日志上报
    	}
    //  ...
    })

    性能标记

    itrace.perfMark(name, type)
    • type:
      • start: 表示标记指标的起始时间点
      • end: 表示标记指标的结束时间点
    • name:
      • bizAvailable: 业务可用
      • wl_avgv1 - wl_avgv5: 自定义指标
    • demo
    setData({...}, function () {
      itrace.perfMark('bizAvailable', 'end')// 设置业务可用结束时间点
    })
    
    itrace.perfMark('wl_avgv1', 'start')// 设置性能指标1的时间起点
    // 指标1相关代码执行开始
    ...
    // 指标1相关代码执行结束
    itrace.perfMark('wl_avgv1', 'end')

    6 附录

    6.1 完整 Demo可参考: 待补充

    Install

    npm i miniapp-reporter

    DownloadsWeekly Downloads

    1

    Version

    1.4.4

    License

    ISC

    Unpacked Size

    297 kB

    Total Files

    14

    Last publish

    Collaborators

    • itracker