腾讯云可观测平台配置文档

配置说明
配置文档各配置项说明如下：
配置
描述
id
必须，string，默认无。
前端性能监控分配的应用 ID。
uin
建议，string，默认取 cookie 中的 UIN 字段。
当前用户的唯一标识符，白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持字母数字@=._-，正则表达式：/^[@=.0-9a-zA-Z_-]{1,60}$/。
reportApiSpeed
可选，boolean 或者﻿ object，默认 false。
﻿
是否开启接口测速，这个开关设置为 true 后，还需在 白名单管理 页面将用户添加为白名单用户，才会将采集到的正常的 api 请求记录到日志中，否则仅在指标分析模块聚合消费。
reportAssetSpeed
可选，boolean，默认 false。
是否开启静态资源测速。
pagePerformance
可选，boolean 或者 ﻿object﻿
，默认 true。
是否开启页面测速。
webVitals
可选，boolean，默认 true。
是否开启 web vitals 测速。
consoleLog
可选，boolean，默认 false。
是否将采集的 console 日志上报为日志。
clickElementLog
可选，boolean，默认 false。
是否将采集的点击事件上报为日志。
ignoreElements
可选，{"ignoreClasses": string[], "ignoreIds": string[]}，
例如 { "ignoreClasses": ["address-box","school-box"], "ignoreIds": ["phone-num-card","name-card"]},
通过元素的 class 和 id 忽略指定元素，用于过滤掉不需要上报的元素，例如用户的个人信息输入框等。
slowApiLog
可选，boolean，默认 false。
是否将采集的慢 api 请求数据上报为日志，慢的标准是请求耗时超过1000ms。
pageLoadLog
可选，boolean，默认 false。
是否将采集的正常页面加载数据上报为日志。
slowPageLoadLog
可选，boolean，默认 false。
是否将采集的慢页面加载数据上报为日志，慢的标准是 fmp 超过1000ms。
assetLog
可选，boolean，默认 false。
是否将采集的正常资源请求数据上报为日志，这个开关设置为 true 后，还需在 白名单管理 页面将用户添加为白名单用户，才会将采集到的正常的资源请求记录到日志中，否则仅在指标分析模块聚合消费。
slowAssetLog
可选，boolean，默认 false。
是否将采集的慢资源请求数据上报为日志，慢的标准是请求耗时超过1000ms。
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 只上报一次测速日志）。
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
})
﻿

配置	描述
id	必须，string，默认无。前端性能监控分配的应用 ID。
uin	建议，string，默认取 cookie 中的 UIN 字段。当前用户的唯一标识符，白名单上报时将根据该字段判定用户是否在白名单中，字段仅支持`字母数字@=._-`，正则表达式：`/^[@=.0-9a-zA-Z_-]{1,60}$/`。
reportApiSpeed	可选，boolean 或者 object，默认 false。是否开启接口测速，这个开关设置为 true 后，还需在白名单管理页面将用户添加为白名单用户，才会将采集到的正常的 api 请求记录到日志中，否则仅在指标分析模块聚合消费。
reportAssetSpeed	可选，boolean，默认 false。是否开启静态资源测速。
pagePerformance	可选，boolean 或者 object ，默认 true。是否开启页面测速。
webVitals	可选，boolean，默认 true。是否开启 web vitals 测速。
consoleLog	可选，boolean，默认 false。是否将采集的 console 日志上报为日志。
clickElementLog	可选，boolean，默认 false。是否将采集的点击事件上报为日志。
ignoreElements	可选，{"ignoreClasses": string[], "ignoreIds": string[]}，例如 { "ignoreClasses": ["address-box","school-box"], "ignoreIds": ["phone-num-card","name-card"]}, 通过元素的 class 和 id 忽略指定元素，用于过滤掉不需要上报的元素，例如用户的个人信息输入框等。
slowApiLog	可选，boolean，默认 false。是否将采集的慢 api 请求数据上报为日志，慢的标准是请求耗时超过1000ms。
pageLoadLog	可选，boolean，默认 false。是否将采集的正常页面加载数据上报为日志。
slowPageLoadLog	可选，boolean，默认 false。是否将采集的慢页面加载数据上报为日志，慢的标准是 fmp 超过1000ms。
assetLog	可选，boolean，默认 false。是否将采集的正常资源请求数据上报为日志，这个开关设置为 true 后，还需在白名单管理页面将用户添加为白名单用户，才会将采集到的正常的资源请求记录到日志中，否则仅在指标分析模块聚合消费。
slowAssetLog	可选，boolean，默认 false。是否将采集的慢资源请求数据上报为日志，慢的标准是请求耗时超过1000ms。
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 只上报一次测速日志）。
dbConfig	可选，Object。
ext1	可选，string，自定义上报的额外维度，上报的时候可以被覆盖。
ext2	可选，string，自定义上报的额外维度，上报的时候可以被覆盖。
ext3	可选，string，自定义上报的额外维度，上报的时候可以被覆盖。

配置文档

本页目录：

配置说明

示例

api.retCodeHandler

api.resourceTypeHandler

reportApiSpeed.urlHandler

pagePerformance.urlHandler