腾讯云可观测平台 API 说明

本文详细介绍终端性能监控 Pro Electron SDK 的各功能接口，帮助您更加灵活、深度的使用 SDK。
插件配置
SDK 通过插件配置管理各个上报的开启和具体配置。
主进程插件配置
在 SDK 初始化的时候添加如下代码。
const aegis = new Aegis({
  id : 'xxxxx',
  appKey: 'xxxxx',
  plugin: {
    processPerformance: true, // 性能，包括cpu和内存
    error: true, // 错误上报
    crash: true, // 崩溃上报
    api: {
      apiDetail: true,
    },
  },
})
渲染进程插件配置
在 SDK 初始化的时候添加如下代码。
{
    plugin: {
          aid?: Boolean | PluginConfigOption;
          pv?: Boolean | PluginConfigOption;
          assetSpeed?: Boolean | PluginConfigOption;
          api?: Boolean | CoreApiConfig;
          error?: Boolean | PluginConfigOption;
          pagePerformance?: Boolean |{longtask: boolean}; // longtask 收集默认关闭，如需开启可设置为{longtask: true}
          spa?: Boolean | PluginConfigOption;
          blankScreen?: Boolean | PluginConfigOption;
    }
}
PluginConfigOption 的配置：
interface PluginConfigOption {
  [key: string]: any;
}
CoreApiConfig 的配置：
type CoreApiConfig = {
  apiDetail?: boolean;
  resourceTypeHandler?: Function | undefined;
  retCodeHandler?: Function | undefined;
  reqParamHandler?: Function | undefined;
  resBodyHandler?: Function | undefined;
  resHeaders?: Array<string>;
  reqHeaders?: Array<string>;
  //必须为枚举值 'traceparent', 'sw8', 'b3', 'sentry-trace' 中的一种，开启该参数后，Aegis V2 会在用户请求头中注入相关 trace header。
  injectTraceHeader?: string;
  //数组中传入 string 或者 RegExp。标记哪些请求 url 需要注入 trace 请求头。
  injectTraceUrls?:Array;
  //数组中传入 string 或者RegExp。标记哪些请求 url 不需要注入 trace 请求头。
  injectTraceIgnoreUrls?: Array;
  //标记trace请求的flag设置
  traceFlag?: boolean || number;
};
说明：
aid：Aegis SDK 为每个用户设备分配的唯一标识，会存储在浏览器的 localStorage 里面，用来区分用户、计算 uv 等。aid 只有用户清理浏览器缓存才会更新。对于一些项目，使用自己构造的 aid 作为上报规则，后端对 aid 的校验规则如下：/^[@=.0-9a-zA-Z_-]{4,36}$/。
API 配置表
配置项
类型
默认值
说明
api
boolean \\| object
{}
设为 true 时等价于 {}，设为 false 时关闭 API 监控
apiDetail
boolean
false
上报接口信息时，是否同时上报请求参数与返回值
reportAbort
boolean
false
上报接口信息时，是否上报接口 abort 的日志
retCodeHandler
Function(data, url, ctx): {isErr: boolean, code: string}
-
返回码上报钩子，可异步；用于自定义判断接口是否异常
reqParamHandler
Function(data, url)
-
上报前对请求参数进行过滤或加工
resBodyHandler
Function(data, url)
-
上报前对响应 body 进行过滤或加工
reqHeaders
Array<string>
-
需要上报的 HTTP 请求头字段列表
resHeaders
Array<string>
-
需要上报的 HTTP 响应头字段列表（需小写；非 simple header 需在响应头加 Access-Control-Expose-Headers）
resourceTypeHandler
Function(url): 'static' \\| 'fetch'
-
自定义请求资源类型修正钩子
injectTraceHeader
'traceparent' \\| 'sw8' \\| 'b3' \\| 'sentry-trace'
-
开启后，Aegis V2 会在匹配到的请求头中注入对应 trace header
injectTraceUrls
Array<string \\| RegExp>
-
指定哪些 URL 需要注入 trace header（字符串为全匹配，推荐用正则）
injectTraceIgnoreUrls
Array<string \\| RegExp>
-
指定哪些 URL 不需要注入 trace header（字符串为全匹配，推荐用正则）
traceFlag
boolean \\| number
-
trace 请求的 flag 标记
urlHandler
Function(url, body): string
-
自定义逻辑返回最终上报的 url
日志
SDK 会主动收集用户的一些性能和错误日志，开发者可以根据不同的参数来配置哪些日志需要上报，以及上报的日志具体信息。
日志类型
LogType 有以下几种类型：
enum LogType {
  NORMAL = 'normal', // 普通日志类型
  PV = 'pv', // 页面 PV
  API = 'api', // API 调用
  API_SPEED = 'api_speed', // API 测速
  CUSTOM_TIME = 'custom_time', // 自定义测速
  CUSTOM_EVENT = 'custom_event', // 自定义事件
  ASSETS_SPEED = 'assets_speed', // 静态资源测速
  PAGE_PERFORMANCE = 'page_performance', // 页面测速
  WEB_VITALS = 'web_vitals', // web_vitals 测速
  SDK_ERROR = 'sdk_error', // sdk 错误
  SESSION = 'session', //会话追踪
  BRIDGE = 'bridge',
  WEBSOCKET = 'websocket',
}
不同的 logType 对应的 message 不一样，以下以 PV、API、页面测速、web_vitals 测速为例说明。
{
    "pv": {
        "msg": "spa"
    },
    "assets_speed": {
        "msg": "asset_speed",
        "url": "xxxx",
        "duration": 4214.3,
        "status": 200,
        "assetType": "static",
        "isHttps": true,
        "nextHopProtocol": "",
        "urlQuery": "",
        "domainLookup": 0,
        "connectTime": 0,
        "transferSize": -1,
        "method": "get"
    },
    "api": {
        "msg": "",
        "url": "xxxx",
        "status": 200,
        "duration": 151,
        "method": "POST",
        "param": "",
        "data": "",
        "reqHeaders": "",
        "resHeaders": "",
        "level": "info",
        "ret": "unknown",
        "isErr": false,
        "trace": "",
        "type": "api",
        "nextHopProtocol": "",
        "plugin": "api"
    },
    "page_performance": {
        "msg": "page_performance",
        "type": "page_performance",
        "dnsLookup": 0,
        "tcp": 0,
        "ssl": 0,
        "ttfb": 14,
        "contentDownload": 1,
        "domParse": 125,
        "resourceDownload": 4651,
        "firstScreenTiming": 1043,
        "plugin": "pagePerformance"
    },
    "web_vitals": {
        "type": "web_vitals",
        "msg": "web_vitals",
        "FCP": 167.5,
        "LCP": 761.4000000059605,
        "FID": -1,
        "CLS": 0.017961352164726968,
        "plugin": "webVitals"
    },
}
最终上报格式示例
{
  "productId": "xxxx",
  "clientIdentify": "xxxx", // string，一次上报的唯一标识
  "bean": { "uid": "...", "env": "...", ... },
  "ext": { "os": "...", "cpu": "...", ... },
  "scheme": "v2",
  "d2": [
    {
      "fields": { "type": "...", "level": "...", ... }, // 后台会更具 type 和 level 判断日志类型
      "message": [ { ... } ]
    }
  ],
  "appKey": "xxxx" // string，产品对应的 appKey
  "v": "0.0.1"
}
钩子函数
SDK 提供了丰富的钩子供用户使用，以下将举例说明 onBeforeSend 钩子函数的使用。
钩子函数调用时机
钩子函数名称
描述
onNewAegis
该钩子将会在 Aegis 初始化时执行
onConfigChange
该钩子将会在使用实例方法 setConfig 时执行
onBeforeCollect
该钩子将会在插件开始收集 log 之前执行
onBeforeProcess
该钩子将会在插件格式化处理 log 之前执行
onProcessed
该钩子将会在插件格式化处理 log 后，开始发送给日志服务之前执行
onBeforeSend
该钩子将在发送给日志服务之前执行
onSended
该钩子将在发送给日志服务之后执行，基本等同于原来的 afterRequest
onBeforeDestroy
该钩子将在调用实例方法 destroy，执行销毁实例逻辑之前执行
onDestroyed
该钩子将在调用实例方法 destroy，执行销毁实例逻辑之后执行
使用示例
onBeforeSend 钩子将在发送给日志服务之前执行，用于对上报数据的拦截和修改。
const aegis = new Aegis({
  id : 'xxx',
  appKey: 'xxxx',
  onBeforeSend: (logs, aegis) => {
    return logs.filter(log => log.type === 'api');
  },
  plugin: {
    pagePerformance: true, // 性能
    error: true, // 错误上报
    api: {  // API上报
      apiDetail: true,
    },
  },
})
所有钩子的参数都是一样的。
onBeforeProcess(logs, Aegis)
logs 的示例内容如下，可以在各个钩子的调用时机对其进行处理。
{
  aegisv2_goto: '3851c4e4a9399dc1',
  timestamp: 1754535777595,
  sysMemory: 30967548,
  sysMemoryPercent: 92.29,
  sysCPUPercent: 5.87,
  mainMemory: 110524,
  mainMemoryPercent: 0.33,
  mainCPUPercent: 0,
  type: 'processPerformance',
  level: 'info',
  plugin: 'processPerformance',
  snapshootInfo: '{}'
}
﻿

配置项	类型	默认值	说明
api	boolean \\\| object	{}	设为 true 时等价于 {}，设为 false 时关闭 API 监控
apiDetail	boolean	false	上报接口信息时，是否同时上报请求参数与返回值
reportAbort	boolean	false	上报接口信息时，是否上报接口 abort 的日志
retCodeHandler	Function(data, url, ctx): {isErr: boolean, code: string}	-	返回码上报钩子，可异步；用于自定义判断接口是否异常
reqParamHandler	Function(data, url)	-	上报前对请求参数进行过滤或加工
resBodyHandler	Function(data, url)	-	上报前对响应 body 进行过滤或加工
reqHeaders	Array<string>	-	需要上报的 HTTP 请求头字段列表
resHeaders	Array<string>	-	需要上报的 HTTP 响应头字段列表（需小写；非 simple header 需在响应头加 Access-Control-Expose-Headers）
resourceTypeHandler	Function(url): 'static' \\\| 'fetch'	-	自定义请求资源类型修正钩子
injectTraceHeader	'traceparent' \\\| 'sw8' \\\| 'b3' \\\| 'sentry-trace'	-	开启后，Aegis V2 会在匹配到的请求头中注入对应 trace header
injectTraceUrls	Array<string \\\| RegExp>	-	指定哪些 URL 需要注入 trace header（字符串为全匹配，推荐用正则）
injectTraceIgnoreUrls	Array<string \\\| RegExp>	-	指定哪些 URL 不需要注入 trace header（字符串为全匹配，推荐用正则）
traceFlag	boolean \\\| number	-	trace 请求的 flag 标记
urlHandler	Function(url, body): string	-	自定义逻辑返回最终上报的 url

钩子函数名称	描述
onNewAegis	该钩子将会在 Aegis 初始化时执行
onConfigChange	该钩子将会在使用实例方法 setConfig 时执行
onBeforeCollect	该钩子将会在插件开始收集 log 之前执行
onBeforeProcess	该钩子将会在插件格式化处理 log 之前执行
onProcessed	该钩子将会在插件格式化处理 log 后，开始发送给日志服务之前执行
onBeforeSend	该钩子将在发送给日志服务之前执行
onSended	该钩子将在发送给日志服务之后执行，基本等同于原来的 afterRequest
onBeforeDestroy	该钩子将在调用实例方法 destroy，执行销毁实例逻辑之前执行
onDestroyed	该钩子将在调用实例方法 destroy，执行销毁实例逻辑之后执行

API 说明

本页目录：

插件配置

主进程插件配置

渲染进程插件配置

API 配置表

日志

日志类型

最终上报格式示例

钩子函数

钩子函数调用时机

使用示例