接口说明

设置用户ID

通过设置「用户标识」在基调听云平台通过该标识进行检索具体用户的性能数据

接口

// username: 用户名，字符串类型。长度限制：
tingyun.setUid(username)

示例

import tingyun from '@/agent/init'

// ... 
tingyun.setUid('<用户id>')

Vue路由监控

接口

// router VueRouter实例对象
tingyun.wrapVueRouter(router);

示例：

// 引入探针
import tingyun from '@/agent/init'

import App from '@/App.vue'
import Home from '@/routes/Home.vue'
import About from '@/routes/About.vue'
import VueRouter from 'vue-router';

Vue.use(VueRouter)

const router = new VueRouter({
  mode: 'abstract',
  routes: [
    { path: '/', redirect: '/home' },
    { path: '/home', component: Home },
    { path: '/about', component: About }
  ]
})

// 调用wrapVueRouter接口传入路由对象
tingyun.wrapVueRouter(router)

new Vue({
  el: '#root', 
  router: router,
  render: h => h(App),
})

JS错误上报

使用该接口可以将触发的 JS 错误上传至基调听云平台，以便研发人员收集和排查 JS 错误。

探针默认会对Vue.config.errorHandler的触发进行监控并上报JS错误。如果项目本身也注册了Vue.config.errorHandler, 当errorHandler在入口文件同步注册时，通常情况下探针可以自动监控「自动监控时需确认 Vue.config.errorHandler 监控有效」。但当errorHandler注册时机较晚时, 探针自动监控会失效，此时，需要在自定义的errorHandler中使用探针API captureException手动上报。

接口

tingyun.captureException(err[, options])

参数:

err: 错误对象
- message：错误信息可选
- stack：错误堆栈可选
- fileName： string 指定错误文件名，可选, 不传自动从stack解析
- lineNumber： number 指定错误行号，可选, 不传自动从stack解析
- columnNumber: number 指定错误列号，可选, 不传自动从stack解析
options: 额外选项。对象类型。可选
- contexts: 额外附加数据。对象类型。可选
- breadcrumbs: 面包屑数据。数组。可选数据项类型说明
  - timestamp: number 毫秒时间戳，必须
  - type: string 类型，必须
  - category: string 分类，必须
  - level: string 等级，必须
  - message: string 信息，可选
  - data: object 附加数据，可选
- category：错误类型。可选。取值： js（JS错误, 默认）或other（其他错误）
示例
自定义errorHandler上报 JS 错误

在自定义的errorHandler内上报JS错误

Vue.config.errorHandler = function (err) {
  // 上报错误
  tingyun.captureException(err)
}

关闭JS错误自动监控开关，防止重复监控

agent/init.js:

tingyun.init({
  // ...
  jsError: {
    // 关闭JS错误自动监控
    enabled: false
  }
})

手动上报错误

部分JS错误触发后，不会触发Vue.config.errorHandler, 此时可以手动上报JS错误

import tingyun from '@/agent/init'

// ...

try {
  // ... 
} catch(e) {
  tingyun.captureException(e)
}

自定义操作

通过调用「自定义操作」接口来定义一个「业务操作」用以分析其性能情况

接口

const action = tingyun.newAction(optionsStart);

action.end(optionsEnd);

参数：

optionsStart 操作配置项对象
- key: 操作名称。字符串类型。必须
- context: 操作包含的附加数据。对象类型。可选
- duration: 设置操作时间, 对于立即发送的操作, 可以设置此配置指定操作时间。number类型。可选
- timeout: 操作超时时间, 默认10分钟, 超时后的操作被丢弃, number类型, 可选
- status: 设置操作状态success或fail, 默认success, 只在立即发送模式的操作有效。字符串类型。可选
- immediate: 是否立即发送此操作, boolean类型, 默认为false。可选
optionsEnd 结束操作配置对象。可选
- context: 操作包含的附加数据。对象类型。可选
- status: 设置操作状态success或fail, 默认success。字符串类型。可选
示例下面示例演示一个提交订单操作

import tingyun from '@/agent/init'

//... 

export default {
  methods: {
    submitOrder(orderId) {
      // 创建一个名称为 submitOrder 的操作
      const action = tingyun.newAction({
        key: 'submitOrder'
      })
      fetch({
        url: '...',
        method: 'POST',
        body: '...'
      }, function (response) {
        if (response.ok) {
          // 提交订单成功, 结束操作
          action.end()
        }else {
          // 提交订单失败, 结束操作，标记操作失败，并上传失败的订单号
          action.end({
            status: 'fail',
            context: {
              orderId: orderId
            }
          })
        }
      })
    }
  }
}

自定义操作使用方式:

使用newAction创建操作，获取操作对象，调用API时操作同时开始
使用操作对象end方法，结束并上报操作。操作会包含操作持续时间内发起的请求
在end方法参数中设置context属性上报自定义数据，设置status属性来设置操作的成功失败状态

配置采集参数

探针支持配置采集stream模块fetch接口发送请求的 URL参数，请求头，请求体，返回头和返回体。

配置格式:

tingyun.init({
  // ...
  common: {
    paramCollection: [
      {
        // number
        type: <采集位置类型>
        key: '<采集字段名>'
      },
      ...
    ]
  }
})

type取值：

1: URL
2: 请求头
3: 请求体, 支持JSON字符串格式的请求体和 application/x-www-form-urlencoded 格式的请求体，支持配置JSON Path
4: 返回头
5: 返回体, 支持JSON格式返回体, 支持配置JSON Path

配置示例：

tingyun.init({
  // ...
  common: {
    paramCollection: [
      // 从URL参数中获取token参数
      {
        type: 1,
        key: 'token'
      },
      // 从请求头中获取 content-type 请求头
      {
        type: 2,
        key: 'content-type'
      },
      // 从请求体中获取delay字段
      {
        type: 3,
        key: 'delay'
      },
      // 从返回头中获取 Server-Timing 返回头
      {
        type: 4,
        key: 'Server-Timing'
      },
      // 配置JSON Path从返回体中获取信息
      // 假如返回体为：{"code":200,"message":"成功","data":[{"id":1,"name":"xxx","lon":116.43,"lat":39.92}]} 
      // 下面配置从返回体data字段的数组的第一项中获取name字段
      {
        type: 5,
        key: 'data[0].name'
      }
    ]
  }
})

配置项

JS SDK支持自定义配置功能项开关，可根据需求配置相应功能项。

// 探针支持的全部配置项
export type ConfigOptions = {
    // 数据上传地址 如果不指定协议默认发https
    domain: string
    // 应用token
    token: string
    // 应用key, 配置tingyun跨应用追踪时必填
    key?: string
    // 应用版本
    release?: string
    // vue router对象
    router?: VueRouterInstance
    // 公共配置
    common?: {
        // 监控路由加载, 默认true
        routerEnabled?: boolean;
        // 采集参数配置
        paramCollection?: ParamCollectConfig[];
      	// 使用domain原始值作为上传地址 默认false 探针检查domain开头不是http:或https:会强制拼接https协议
        // 如果要使用完全自定义的地址发送, 将此选项设为true
        useRawDomain?: boolean;
    }
    // JS错误监控配置
    jsError?: {
        // 自动监控JS错误开关, 默认true
        enabled?: boolean
      	// 接收native监控到js错误后发送的事件, 默认true
        nativeErrorEnabled?: boolean
        // 上报空文件名的js错误, 默认true
        uploadEmptyFileErrors?: boolean
      	// 使用globalEvent模块时注册的事件名称, 默认tingyunWeexError
        nativeErrorEventName?: string
    }
    // Ajax监控配置
    ajax?: {
        // Ajax监控总开关, 默认true
        enabled?: boolean
    }
    // 跨应用追踪配置
    requestTracing?: {
      // trace propagator配置, 默认tingyun, 可选值: tingyun, sw8, w3c-trace-context
      propagators?: string[]
      // 指定加入propagator头的URL，包含关系
      propagationTargets?: string[]
    }
}

type VueRouterInstance = {
    afterEach: any
    [key: string]: any
};

const ParamCollectTypes = {
    URL: 1,
    REQ_HEADER: 2,
    REQ_BODY: 3,
    RES_HEADER: 4,
    RES_BODY: 5,
} as const

type ParamCollectType = typeof ParamCollectTypes[keyof typeof ParamCollectTypes];

// 采集参数配置项
type ParamCollectConfig = {
    type: ParamCollectType
    key: string
}

接口说明

设置用户ID​

Vue路由监控​

JS错误上报​

自定义操作​

配置采集参数​

配置项​

设置用户ID

Vue路由监控

JS错误上报

自定义操作

配置采集参数

配置项