SLS web数据采集上报SDK

1 开通Web Tracking

• 控制台方式

1. 登录日志服务控制台。
2. 在Project列表区域，单击目标Project。
3. 在日志存储 > 日志库页签中，选择目标Logstore（默认是：sls-alysls-track-base）右侧的**** > 修改。
4. 在Logstore属性页面，单击右上方的修改。
5. 打开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
 }
}

• 注意事项：

1. 设置withBody为true和withResp为true时，会在ajax异常(http status < 200 或 http status >=300)时，上报request body和response body（http status >= 200 且 https status <= 299 时不会上报）
2. 请务必检查 request body 和 request body中是否包含敏感数据，若包含敏感数据，建议通过全局beforeSend函数进行过滤
3. 默认自动上报所有基于 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自行上报

.reportBlankPage(logData)

用于主动上报一条白屏日志 适用场景： 用户主动上报白屏日志，比如 当某核心数据接口访问失败或者核心元素没有如期出现时，如果认定页面必定白屏可通过该接口上报。

.setConfig(opts)

更新sdk实例配置

.install()

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

.installAll()

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

.uninstall()

卸载探针实例，销毁所有监听实例，主动上报、自动上报功能不再生效

.diagnose()

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