高级功能
设置用户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
}