腾讯云可观测平台
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 腾讯云可观测平台 > 前端性能监控 > 接入指南 > Web 应用场景 > 配置文档

配置文档

最近更新时间：2024-02-23 14:27:11

我的收藏

本页目录：

配置说明

配置文档各配置项说明如下：
配置
描述
id
必须，string，默认无。
前端性能监控分配的应用 ID。
uin
建议，string，默认取 cookie 中的 UIN 字段。
当前用户的唯一标识符，白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持字母数字@=._-，正则表达式：/^[@=.0-9a-zA-Z_-]{1,60}$/。
reportApiSpeed
可选，boolean 或者
 object，默认 false。

是否开启接口测速。
reportAssetSpeed
可选，boolean，默认 false。
是否开启静态资源测速。
pagePerformance
可选，boolean 或者
object
，默认 true。
是否开启页面测速。
webVitals
可选，boolean，默认 true。
是否开启 web vitals 测速。
onError
可选，boolean，默认 true。
当前实例是否需要进行错误监听，获取错误日志。
aid
可选，boolean，默认 true。
当前实例是否生成 aid。
random
可选，number，默认 1。
0 - 1 抽样率。 0 表示全部不上报。
spa
可选，boolean，默认 false。
当前页面是否为单页应用，若为 true，则将监听 hashchange 及 history api，在页面跳转时进行 PV 上报。
pageUrl
可选。默认是 location.href。
修改上报数据中页面地址，开发者可以主动对数据进行聚合和降低维度。
version
可选，string，默认 SDK 版本号。
当前上报版本，当页面使用了 pwa 或者存在离线包时，可用来判断当前的上报是来自哪一个版本的代码，仅支持字母数字.,:_-，长度在 60 位以内 /^[0-9a-zA-Z.,:_-]{1,60}$/。
delay
可选，number，默认 1000ms。
上报节流时间，在该时间段内的上报将会合并到一个上报请求中。
repeat
可选，number，默认 5。
重复上报次数，对于同一个错误超过多少次不上报。同一个接口上报测速数据的次数。
env
可选 enum，默认 Aegis.environment.production。当前应用运行所处的环境，详情请参见说明文档 环境控制。
websocketHack
可选，boolean，默认 false。
是否开启 websocket 监控。开启该选项后，将会对 websocket 连接断开状态进行监控，但是新建操作仍需要自定义监控。
api
可选，object，默认为 {}。相关的配置：
apiDetail：可选，boolean，默认false。上报 api 信息的时候，是否上报 api 的请求参数和返回值。
retCodeHandler：Function(data: String, url: String, xhr: Object):{isErr: boolean, code: string}， 返回码上报钩子函数。 会传入接口返回数据，请求 url 和 xhr 对象；详情请参见示例 api.retCodeHandler。
reqParamHandler：Function(data: any, url: String) 上报请求参数的处理函数，可以对接口的请求参数进行处理，方便用户过滤上报请求参数的信息。
resBodyHandler：Function(data: any, url: String) 上报 response 返回 body 的处理函数，可以对接口返回值的 response body 进行处理，只上报关键信息。
resourceTypeHandler：Function，请求资源类型修正钩子函数会传入接口 url，返回值为static或 fetch。
reportRequest：boolean，默认：false。开启后，aegis.info 会变成全量上报，不需要白名单配置，并且会上报所有接口的信息（上报接口需开启 reportApiSpeed）。
reqHeaders：Array 需要上报的 HTTP 请求 request headers 列表。
resHeaders：Array 需要上报的 HTTP 请求 response headers 列表。如果开发者需要获取的字段非 “simple response header”，需要给在返回头中给字段添加 Access-Control-Expose-Headers。
usePerformanceTiming：boolean，默认：false。aegis sdk 默认使用打点的方式计算接口耗时，该方式在移动端存在一些误差，开启 usePerformanceTiming 后，aegis sdk 会从 performance 中重新获取接口耗时，让接口耗时统计更为准确。需要注意的是，开启该参数的前提是用户业务接口请求 url 是独立且唯一的，用户可以在接口请求 url 中添加时间戳等方式来保证 url 唯一性。如果 url 不唯一，可能导致同 url 接口耗时获取错误。
injectTraceHeader：可选，string，且必须为枚举值 'traceparent'、'sw8'、'b3'、'sentry-trace' 中的一种，开启该参数后，Aegis 会在用户请求头中注入相关 trace header。详细用法参考 腾讯云可观测平台全链路接入。
injectTraceUrls：可选，Array，数组中传入 string 或者 RegExp。标记哪些请求 url 需要注入 trace 请求头。
injectTraceIgnoreUrls：可选，Array，数组中传入 string 或者 RegExp。标记哪些请求 url 不需要注入 trace 请求头。
speedSample
可选，boolean，默认 true。
测速日志是否抽样（限制每条 url 只上报一次测速日志）。
hostUrl
可选，默认是https://aegis.qq.com。
影响全部上报数据的 host 地址，设置 hostUrl 后，下面几个 URL 地址都会被覆盖。
url
可选，string，默认https://aegis.qq.com/collect。
日志上报地址。
设置为空字符串可以不进行日志上报。
pvUrl
可选，string，默认https://aegis.qq.com/collect/pv。
pv 上报地址。
设置为空字符串可以不进行 pv 上报。
whiteListUrl
可选，string，默认https://aegis.qq.com/collect/whitelist。
设置白名单确认接口。进入 前端性能监控控制台，选择左侧导航栏的应用管理>白名单管理进行设置。
设置为空字符串可以关闭白名单接口请求。
eventUrl
可选，string，默认https://aegis.qq.com/collect/events。
设置自定义事件上报地址。
设置为空字符串可以不进行自定义事件上报。
speedUrl
可选，string，默认https://aegis.qq.com/speed。
测速日志上报地址。
设置为空字符串可以不进行测速数据上报。
customTimeUrl
可选，string，默认https://aegis.qq.com/speed/custom。
设置自定义测速上报地址。
设置为空字符串可以不进行自定义测速上报。
performanceUrl
可选，string，默认https://aegis.qq.com/speed/performance。
设置页面性能日志上报地址。
设置为空字符串可以不进行页面性能上报。
webVitalsUrl
可选，string，默认https://aegis.qq.com/speed/webvitals。
设置 webvitals 上报地址。
设置为空字符串可以不进行 web-vitals 上报。
dbConfig
可选，Object。
ext1
可选，string，自定义上报的额外维度，上报的时候可以被覆盖。
ext2
可选，string，自定义上报的额外维度，上报的时候可以被覆盖。
ext3
可选，string，自定义上报的额外维度，上报的时候可以被覆盖。

示例

api.retCodeHandler

假如后台返回数据为：
{
   body: {
      code: 200,
      retCode: 0,
      data: {
          // xxx
      }
   }
}

业务需要：code 不为200，或者 retCode 不为0，此次请求就是错误的。此时只需进行以下配置：
new Aegis({
    // xxx
    reportApiSpeed: true, // 需要开两个，不然不会有返回码上报
    reportAssetSpeed: true,
    api: {
        retCodeHandler(data, url, xhr) { 
            // data 是string类型，如果需要对象需要手动parse下
            // url 为请求url
            // xhr 响应,可以通过xhr.response拿到完整的后台响应
            try {
                data = JSON.parse(data)
            } catch(e) {}
            return {
                // isErr 如果是 true 的话，会上报一条 retcode 异常的日志。
                isErr: data.body.code !== 200 || data.body.retCode !== 0,
                code:  data.body.code
            }
        }
    }
})

api.resourceTypeHandler

假如接口为：http://example.com/test-api 。返回的 Content-Type 为 text/html，这将导致 Aegis 认为该接口返回的是静态资源，可以通过以下方法修正：
new Aegis({
    reportApiSpeed: true, // 需要开两个，不然不会有返回码上报
    reportAssetSpeed: true,
    api: {
        resourceTypeHandler(url) {
            if (url?.indexOf('http://example.com/test-api') != -1) {
                return 'fetch';
            }
        }
    }
})

reportApiSpeed.urlHandler

假如您页面中有 restful 风格的接口，例如：
www.example.com/user/1000
www.example.com/user/1001
在上报测速时需要将这些接口聚合：
new Aegis({
    // xxx
    reportApiSpeed: {
        urlHandler(url, payload) {
            if ((/www\\.example\\.com\\/user\\/\\d*/).test(url)) {
                return 'www.example.com/user/:id';
            }
            return url;
        }
    }
    // xxx
})

pagePerformance.urlHandler

假如您的页面 URL 是 restful 风格的，例如：
www.example.com/user/1000
www.example.com/user/1001
在上报页面测速时需要将这些页面地址聚合：
new Aegis({
    // xxx
    pagePerformance: {
        urlHandler() {
            if ((/www\\.example\\.com\\/user\\/\\d*/).test(window.location.href)) {
                return 'www.example.com/user/:id';
            }
        }
    }
    // xxx
})

中国站