Sls-wpk-reporter NPM

SLS web数据采集上报SDK

1 开通Web Tracking

控制台方式

登录日志服务控制台。
在Project列表区域，单击目标Project。
在日志存储 > 日志库页签中，选择目标Logstore（默认是：sls-alysls-track-base）右侧的 > 修改。
在Logstore属性页面，单击右上方的修改。
打开WebTracking开关，并单击保存。

2 SDK引入

1. 安装依赖
npm i sls-wpk-reporter --save
 
2. 引入核心
import SlsReporter from 'sls-wpk-reporter'
 
3. 引入插件
import {
  wpkglobalerrorPlugin, // js错误监控
  wpkperformancePlugin, // 性能监控
} from 'sls-wpk-reporter'

3 上报

3.1 demo预览

const wpk = new SlsReporter({
  bid: 'sls-f51778cfbdfbfa4573', // 应用标识（非移动运维监控接入不需要填写）
  project: '', // 项目project（必填）
  endpoint: '', // project对应的endpoint（必填）
  slsParams: { // 扩展字段，会同采集的日志一并写入（非必填）
    app_name: '', // app中文名称
    user_nick: '', // 登录nick
    logon_type: '', // 登录类型
  },
  rel: '', // 前端资源版本号，推荐设置（非必填）
  uid: '', // 用户唯一ID，推荐设置（非必填）
  plugins: [ // 采集插件
    [wpkperformancePlugin],
    [
      wpkglobalerrorPlugin,
      {
        jsErr: true, // 是否开启js error监控
        resErr: true, // 是否开启资源加载异常监控
      },
    ],
  ],
});
wpk.install(); // 初始化！一定记得调用
// 现在，试一下主动上报一条日志
wpk.logReport({
  key1: '1',
  key2: '2'
})

3.2 配置参数

bid 必填

移动运维监控应用标识，新建后分配

project 必填

采集上报的project

endpoint 必填

project对应的endpoint

slsParams 选填

日志上报扩展字段，类型为object

topic 可选

日志的topic，类型为string

rel 可选，推荐设置

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

uid 可选，推荐设置

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

plugins 可选

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

sampleRate 可选

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

beforeSend 可选

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

spa 可选

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

debug 可选

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

4 插件

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

4.1 使用方式

4.1.1 构造方法传参

import wpkinterfacePlugin from 'sls-wpk-reporter/src/plugins/interface'
const wpk = new SlsReporter({
  // ...
  plugins: [[
    wpkinterfacePlugin, { sampleRate: 0.5 }
  ]],
  // ...
})

4.1.2 接口方式

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

4.2 插件列表

4.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

4.2.2 wpkinterfacePlugin - 接口异常监控

参数： opts

{
  enable: true, // 默认为 true，可设为false关闭插件功能
  sampleRate: 1,  // 采样率，默认为 1
  withBody: false, // 是否上报请求的body参数，可能涉及敏感信息，故默认 false
  withResp: false, // 上报日志是否包含api返回数据，可能涉及敏感信息，故默认 false
  errorFilter: function(params) {
    // 异常过滤回调函数，参数包含 请求地址、响应码及响应内容，返回 false则不上报
    /* params格式为
    {
      url: '',
      status: '',
      response: '',
      body: '',
      reqHeaders: {},
      resHeaders:{},
      queryString: ''
    }
    */
    // 返回值可以是 false 或者 Object 对象。返回false 则此次api数据直接丢弃
    return customParams
 }
}

注意事项：

设置withBody为true和withResp为true时，会在ajax异常(http status < 200 或 http status >=300)时，上报request body和response body（http status >= 200 且 https status <= 299 时不会上报）
请务必检查 request body 和 request body中是否包含敏感数据，若包含敏感数据，建议通过全局beforeSend函数进行过滤
默认自动上报所有基于 xhr或 fetch的异步请求，有特殊情况的可通过 errorFilter自定义

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

参数: opts

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

4.2.4 wpkflowPlugin - 站点流量监控参数：opts，{ spa: false }

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

5 前端框架支持

Vue

Vue框架的支持是通过劫持Vue.config.errorHandler 监听并上报JS异常，若您已经有自己的全局异常处理器，也可自行上报，如下所示:

// vue2.0
Vue.config.errorHandler = function(error, vm, info) {
  wpk.reportError(error, {c1: vm.$options.name})
}
// vue3.0
app.config.errorHandler = function(error, vm, info) {
  wpk.reportError(error, {c1: vm.$options.name})
}

插件使用

Vue 2.0

import SlsReporter, { wpkvuePlugin } from 'sls-wpk-reporter'
const wpk = new SlsReporter({
	bid: 'yourBid'
})
wpk.installAll()
wpk.addPlugin(wpkvuePlugin, Vue)

Vue 3.0

import { createAPp } from 'vue'
import App from './App.vue'
import SlsReporter, { wpkvuePlugin } from 'sls-wpk-reporter'
const wpk = new SlsReporter({
	bid: 'yourBid'
})
wpk.installAll()
const app = createApp(App)
// 以下两行先后顺序可自己决定
// 添加挂件
wpk.addPlugin(wpkvuePlugin, app)
// 挂载APP
app.mount('#app')

React

从React16开始，react引入了错误边界的概念，自 React 16 起，任何未被错误边界捕获的错误将会导致整个 React 组件树被卸载(事件处理器内部错误不会)

sls-wpk-reporter 便是利用边界中的 componentDidCatch 捕获并上报边界异常。因此若您已经为您的APP设计了边界组件，那么直接在componentDidCatch中上报JS异常即可。如下所示

class ErrorBoundary extends React.Component {
  ...
  componentDidCatch (error, errorInfo) {
    wpk.reportError(error, {bl1: errorInfo.componentStack})
  }
  ...
}

6 API

说明

每条上报的数据 logData，我们称之为一条日志数据，类型为 Object
logData的属性包含SDK所有构造参数，除此之外，还可以包含以下属性： 构造参数为全局，logData参数则为单次有效，即只影响单次的上报
所有api均返回当前sdk实例，因此你可以方便的进行链式调用

.logReport(logData)

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

.reportFlow()

主动上报一条打点日志，上报一次，平台“页面访问”中的pv会增加1。

.reportError(error)

用于主动上报一条JS Error日志。error为JS Error对象。

.reportApiError(data, extra)

用于主动上报一条API监控日志(从0.9.9开始增加.reportApi(data, extra) 等效 reportApiError)

// 参数格式data：
{
  msg: '', // api响应信息
  url: '', // api url
  method: '',
  queryString: '', // 自行格式化为 a=1&b=2，也支持直接传Object
  body: '', // 请求body
  response: '',
  status: '', // http status
  spent: 0, // 耗时，，有效值为数字
  c1: '', c2: '', c3: '', c4: '', c5: ''
}
// extra 当前支持
{
  bl1: '', c2: '', c3: '', c4: '', c5: ''
}

适用场景：探针本身已经支持对api进行监控，api请求的成功失败，通过 status 的值判断，若您的api返回值都是200，而通过response body判断中的自定义code 判断，建议使用此api自行上报