wpk-reporter

    0.9.3 • Public • Published

    JS探针采集

    1 SDK引入

    SDK共有两种方式引入,分别为 npm模块方式,以及普通的 script 标签引入。

    1.1 script方式(支持https)

    <!-- 核心引入 -->
    <script src="https://g.alicdn.com/woodpeckerx/jssdk/wpkReporter.js" crossorigin="true"></script>
    <!-- 插件引入 -->
    <script src="https://g.alicdn.com/woodpeckerx/jssdk/plugins/globalerror.js" crossorigin="true"></script>
    <!-- combo方式 -->
    <script src="https://g.alicdn.com/woodpeckerx/jssdk??wpkReporter.js,plugins/globalerror.js" crossorigin="true"></script>

    1.2 script方式快捷引入

    <!-- 快捷引入(探针):导入+自动初始化 -->
    <!-- 注意:引入这段脚本后将启用SDK所有的上报功能,建议阅读完文档再决定是否直接引用 -->
    <script>
    !(function(c,i,e,b){var h=i.createElement("script");var f=i.getElementsByTagName("script")[0];h.type="text/javascript";h.crossorigin=true;h.onload=function(){c[b]||(c[b]=new c.wpkReporter({bid:"wpktest"}));c[b].installAll()};f.parentNode.insertBefore(h,f);h.src=e})(window,document,"https://g.alicdn.com/woodpeckerx/jssdk/wpkReporter.js","__wpk");
    </script>

    1.3 npm模块方式

    1. 安装依赖
    npm i wpk-reporter --save
     
    2. 引入核心
    import wpkReporter from 'wpk-reporter'
     
    3. 引入插件
    import wpkinterfacePlugin from 'wpk-reporter/dist/plugins/interface'

    2 上报

    2.1 demo预览

    const wpk = new wpkReporter({
      bid: 'wpk新建应用后分配',
      rel: '', // 支持函数,需返回最终的版本字符串'
      uid: '', // 支持函数,需返回最终的uid字符串
      plugins: [], // 可选
      spa: false   // 如果你的应用是spa,那就大胆的设为true吧,默认false
    })
    wpk.install() // 初始化!一定记得调用
    // 现在,试一下主动上报一条日志
    wpk.report({
      category: 100, // 必填,一般是100以上的数字,1~99为预留为系统使用
      msg: 'hello wpk'
    })

    2.2 配置参数

    • bid 必填

    啄木鸟平台应用标识,新建后分配

    • rel 可选,推荐设置

    前端资源版本号,强烈推荐设置
    支持字符串以及函数两种方式设置,函数最终需要返回一个字符串

    • uid 可选,推荐设置

    浏览当前页面的用户唯一标识,强烈推荐设置,默认为 uuid
    支持字符串以及函数两种方式设置,函数最终需要返回一个字符串

    • plugins 可选

    需要开启的插件
    没有设置任何插件时,默认加载 wpkflowPlugin 用于上报站点流量数据

    • sampleRate 可选

    采样率,大业务(日志量大于 xxx / 天)推荐设置
    默认规则,除了 性能数据的采样率为 10%,其余类型的日志均为 100%

    • beforeSend 可选

    参数为完整的 logData对象
    日志上报的前置处理,返回 false可阻止日志上报,否则返回true(记得一定要返回)

    • spa 可选

    是否spa应用,默认 false
    设为 true后,可配合 wpkflowPlugin更好的打点(自动监听hashchange)

    • debug 可选

    开启debug模式,默认 false
    开启后,将会有更详细的打点过程日志输出,一般用于接入时联调分析,生产环境不建议打开

    • ignoreScriptError 可选

    是否忽略 'Script Error'即第三方脚本错误,默认为 true

    • onlyCustom 可选(同时接入内核高可用的业务需关注)

    是否关闭静默上报(插件提供的功能),只保留自定义上报功能,默认为 false
    用途:用于规避内核上报的数据与jssdk的数据出现重复,同时也浪费流量,普通业务无需关注

    3 插件

    sdk核心默认只包含自定义打点,业务可按需添加插件,扩展sdk的打点能力。

    3.1 使用方式

    3.1.1 构造方法传参

    import wpkinterfacePlugin from 'wpk-reporter/dist/plugins/interface'
    const wpk = new wpkReporter({
      // ...
      plugins: [[
        wpkinterfacePlugin, { sampleRate: 0.5 }
      ]],
      // ...
    })
    // 如果是script方式引入插件,也可以直接使用 wpkinterfacePlugin变量

     

    3.1.2 接口方式

    // 确保已经引入
    import wpkinterfacePlugin from 'wpk-reporter/dist/plugins/interface'
    // ... ...
    wpk.addPlugin(interfacePlugin, { sampleRate: 0.5 })

    3.2 插件列表

    • 3.2.1 wpkglobalerrorPlugin (含 jserror resourceError) - 全局错误监控

    参数:opts

    {
      jsErr: true, // 是否开启js error监控
      jsErrSampleRate: 1, // js error采样率,默认为 1
      jsErrFilter: fn, // js error过滤回调函数,参数为 error对象,返回 false则不上报
      resErr: false, // 是否开启资源加载异常监控
      resErrSampleRate: 1 // 资源异常监控采样率,默认为 1
      resErrFilter: fn // 资源加载异常过滤的回调函数,参数为 error对象,返回 false则不上报
    }

    默认只会捕获 js error(包括unhandledrejection),需要监控资源加载异常可以设置 resErr: true

    • 3.2.2 wpkinterfacePlugin - 接口异常监控

    参数: opts

    {
      enable: true, // 默认为 true,可设为false关闭插件功能
      sampleRate: 1,  // 采样率,默认为 1
      withBody: false, // 是否上报请求的body参数,默认 false
      errorFilter: function(params) {
        // 异常过滤回调函数,参数包含 请求地址、响应码及响应内容,返回 false则不上报
        // params格式为 {url: '', status: '', response: '', body: '', reqHeaders: {}, resHeaders:{},queryString: ''}
        // 业务可返回 {bizCode: '', msg: '', traceId: ''},sdk会将他们一并上报
     }
    }

    默认自动上报所有基于 xhr或 fetch的异步请求,有特殊情况的可通过 errorFilter自定义

    Set Access-Control-Allow-Headers when allowing headers to be passed from the client to the server (e.g. If-Match). Set Access-Control-Expose-Headers when allowing headers to be passed back from the server to the client (e.g. ETag)


    3.2.3 wpkperformancePlugin - 基础性能数据自动上报

    参数: opts

    {
      enable: true, // 默认为 true,可设为false关闭上报
      sampleRate: 0.1 // 采样率,默认 100%
    }

    3.2.4 wpkflowPlugin - 站点流量监控
    参数:opts,{ spa: false  }

    参数:opts,{ enable: true // 默认开启 } 默认在 onload时会自动上报
    在sdk构造参数中设置 spa: true,则在hashchange的时候也会自动上报

    4 API

    说明

    • 每条上报的数据 logData,我们称之为一条日志数据,类型为 Object
    • logData的属性包含SDK所有构造参数,除此之外,还可以包含以下属性:

    构造参数为全局,logData参数则为单次有效,即只影响单次的上报

    category 日志监控分类(比如 性能、接口、js错误等)
    1 ~ 99为系统保留,自定义监控项由100开始,已分配的值:
    1 js错误,2 api,3 首屏性能,4 资源加载错误,5 页面访问,6 白屏, 7 harlog

    msg 日志描述信息
    c1 自定义字段1
    c2 自定义字段2
    c3 自定义字段3
    c4 自定义字段4
    c5 自定义字段5

    • 所有api均返回当前sdk实例,因此你可以方便的进行链式调用

    .report(logData)

    主动上报一条日志,日志内容为 logData

    .reportFlow(logData)

    主动上报一次访问的打点,logData参数可选,需要额外参数时可赋值

    .reportError(error, logData)

    主动上报一个jserr类型的打点,额外参数可在 logData中设置

    .reportApiError(data)

    主动上报接口异常日志,data为一个Object类型的参数,字段包含

    {
      msg: '',
      url: '',
      method: '',
      queryString: '',
      body: '',
      response: '',
      status: '',
      spent: ''
      c1: '', c2: '', c3: '', c4: '', c5: ''
    }

    .setConfig(opts)

    更新sdk实例配置

    .install()

    sdk安装,即初始化所有的设置,包含各个插件的初始化(在plugins参数中指定)等
    调用此方法后,sdk的初始化工作才算完成,下面才能成功调用其他API

    .installAll()

    sdk安装,初始化所有的设置,包含内置的所有插件,及安装全家桶,适合不接内核的场景

    .diagnose()

    诊断函数,方便调试
    调用后会在浏览器控制台输出诊断信息,并重定向到一个新页面,显示上报结果

    Install

    npm i wpk-reporter

    DownloadsWeekly Downloads

    58

    Version

    0.9.3

    License

    ISC

    Unpacked Size

    70.8 kB

    Total Files

    9

    Last publish

    Collaborators

    • itracker