文档中心

配置插件

最近更新时间：2024.01.23 20:08:50

首次发布时间：2022.03.16 11:20:41

插件配置是应用性能监控全链路版内置的功能，您可以在SDK侧配置是否开启和关闭这些插件。插件配置属于一次性配置，初始化后修改不能生效。

关闭插件

SDK支持关闭任意插件。如果您要关闭某个插件，将对应的pluginName配置为false。

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    [pluginName]: false // 具体的pluginName可以查看各个插件的配置示例
  },
  ...
})


// 关闭插件示例: 关闭性能插件
browserClient('init', {
  ...
  plugins: {
    performance: false // 具体的pluginName可以查看各个插件的配置示例
  },
  ...
})

配置插件

除了白屏监控，所有插件都有默认配置，默认不需要额外配置。具体默认参数可见下文详细说明，如果有与默认配置不同的地方，可以单独配置。

PV插件

可配置字段说明

字段	类型	默认值	说明
sendInit	boolean	TRUE	页面首次加载时，是否发送PV。如果业务手动发送PV，则可以设置为false。
routeMode	string	history	选择自动监控路由的模式，手动指定当前站点的路由模式。 history：监控path变化 hash：监控hash变化 manual：不自动监控路由变化
extractPid	(url: string) => string	-	手动指定pid的生成规则，传入当前页面地址。返回值作为pid。默认情况下，pid是自动获取当前页面url的pathname或者hash。如果自动生成的pid过于分散，不利于分析数据，可以配置这个函数，达到手动聚合的效果。

字段

类型

默认值

说明

sendInit

boolean

TRUE

页面首次加载时，是否发送PV。如果业务手动发送PV，则可以设置为false。

routeMode

string

history

选择自动监控路由的模式，手动指定当前站点的路由模式。

history：监控path变化
hash：监控hash变化
manual：不自动监控路由变化

extractPid

(url: string) => string

手动指定pid的生成规则，传入当前页面地址。返回值作为pid。
默认情况下，pid是自动获取当前页面url的pathname或者hash。如果自动生成的pid过于分散，不利于分析数据，可以配置这个函数，达到手动聚合的效果。

配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    pageview: {
      routeMode: 'hash',
      extractPid: (url) => {
        return new URL(url).pathname
      }
    }
  },
  ...
})

JS错误插件

可配置字段说明

字段	类型	默认值	说明
ignoreErrors	（string \| RegExp）[]	[]	与error message匹配，忽略能匹配的JS错误。
onerror	boolean	true	是否开启全局onerror监听。如果业务本身是三方组件或者SDK，可以设置为false，表示不开启全局onerror监听，此时需要使用captureException手动上报JS错误。
onunhandledrejection	boolean	true	是否开启全局onunhandledrejetion监听。如果业务本身是三方组件或者SDK，可以设置为false，表示不开启全局onunhandlerejection监听，此时需要使用captureException手动上报JS错误。
captureGlobalAsync	boolean	false	是否hook全局异步API。异常API内的错误，比如setTimeout，因为自身限制抛到全局后往往没有完整堆栈，如果将此字段设置为true，那么可以获得更多信息，例如错误是从哪个API被抛出的。
dedupe	boolean	true	当前发生的JS错误会和上一个错误比较，如果是同一个错误，是否不再上报。为了避免循环上报，默认开启了去重。如果业务场景希望相同的错误能够重复上报，需要将此字段设置为false。

配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    jsError: {
      ignoreErrors: ['Failed to fetch']
    }
  },
  ...
})

面包屑插件

面包屑插件并不是一个独立的功能插件，而是JS错误插件的附属插件，该插件能够给JS错误提供更多的用户相关的行为上下文。

可配置字段说明

字段	类型	默认值	说明
maxBreadcrumbs	number	20	内存里最多能记录多少条面包屑。如果业务场景希望能够看到JS错误发生前更早的用户行为，可以将maxBreadcrumbs的取值设置的大一点。
dom	boolean	true	是否监听click和keypress事件。目前SDK只采集了xpath数据，如果业务对用户隐私仍有安全考虑，可以将dom配置为false，这样就不会采集用户行为。
onAddBreadcrumb	(b: Breadcrumb) => Breadcrumb	-	添加面包屑的钩子函数。常用于部分脱敏场景，或者补充更多上下文。
onMaxBreadcrumb	(bs: Breadcrumb[], maxBreadcrumbs: number) => Breadcrumb[]	-	面包屑队列达到长度限制的钩子函数。常用于一次性处理队列里的面包屑。

类型说明

interface Breadcrumb {
  /** dom | http ｜ any string */
  type: string;
  /** xpath, keyvalue | url */
  message: string;
  /** ui.click, ui.keypress | post,get */
  category: string;
  /** status: 400 for http */
  data?: { [key: string]: string };
}

配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    breadcrumb: {
      dom: false,
      maxBreadcrumbs: 50,
      onAddBreadcrumb: (b) => {
        return {
          ...b,
          data: null // 置空敏感数据
        }
      }
    }
  },
  ...
})

静态资源性能插件

可配置字段说明

字段	类型	默认值	说明
ignoreUrls	(string \| RegExp)[]	[]	指定忽略的资源路径。如果匹配上，则不会上报对应的资源性能数据。
slowSessionThreshold	number	4000	慢会话阈值，单位ms。注意如果会话在阈值时间内未加载完毕，那么即使配置了采样率，当前会话的静态资源性能数据也会全部上报，便于更好的排查页面性能异常。
ignoreTypes	string[]	['xmlhttprequest', 'fetch', 'beacon']	指定忽略的资源类型，对应匹配的字段为PerformanceResourceTiming.initiatorType，详情请参见PerformanceResourceTiming.initiatorType。

配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    resource: {
      ignoreTypes: ['css'],
    }
  },
  ...
})

静态资源错误插件

可配置字段说明

字段	类型	默认值	说明
ignoreUrls	(string \| RegExp)[]	[]	指定忽略的资源路径。如果匹配上，则不会上报对应的静态资源错误。
includeUrls	(string \| RegExp)[]	[]	指定命中的资源路径。如果没匹配上，则不会上报对应的静态资源错误。优先级高于`ignoreUrls`。
dedupe	boolean	true	当前发生的资源错误会和上一个资源错误比较，如果是同一个错误，是否不再上报。为了避免循环上报，默认开启了去重。如果业务场景希望相同的资源错误能够重复上报，需要将此字段设置为false。

配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    resourceError: {
      dedupe: false,
    }
  },
  ...
})

XHR监控插件

可配置字段说明

字段	类型	默认值	说明
autoWrap	boolean	true	是否自动包装全局的xhr。如果业务使用的不是全局的xhr，而是自己包装的xhr，需要将此字段设置为false，同时调用wrapXhr方法手动包装xhr。
ignoreUrls	(string \| RegExp)[]	[]	指定忽略的请求路径，如果匹配上，则不会上报对应的请求数据。
collectBodyOnError	boolean	false	错误时是否采集request body和response body。默认情况下，SDK不会采集request body和response body。如果业务需要错误时采集这些数据便于更好的排查问题，需要将此字段设置为true。注意海外业务可能涉及安全风险，不建议开启此字段。
trace	{ sampleRate?: number, origins: (string \|RegExp)[] } \| boolean	false	配置前后端打通，如果请求路径命中配置的origins，则会在请求头里补充x-rum-traceparent头，便于服务端监控串联整个链路，帮助排查请求耗时长的原因，具体定位请求性能瓶颈。详情请参见全链路场景接入。
extractUrl	(originalUrl: string) => string	-	自定义请求路径的生成规则，传入原始路径，返回值作为新的请求路径。常用于聚合RESTFUL请求路径。

配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    ajax: {
      autoWrap: false,
      collectBodyOnError: true,
    }
  },
  ...
})

Fetch监控插件

可配置字段说明

字段	类型	默认值	说明
autoWrap	boolean	true	是否自动包装全局的fetch。如果业务使用的不是全局的fetch，而是自己包装的fetch，需要将此字段设置为false，同时调用wrapFetch方法手动包装fetch。
ignoreUrls	(string \| RegExp)[]	[]	指定忽略的请求路径，如果匹配上，则不会上报对应的请求数据。如果需要手动忽略某些请求路径，可以配置该字段。
collectBodyOnError	boolean	false	错误时是否采集request body。默认情况下，SDK不会采集request body和response body。如果业务需要错误时采集这些数据便于更好的排查问题，需要将此字段设置为true。注意海外业务可能存在安全风险，不建议开启该字段。
trace	{ sampleRate?: number, origins: (string \|RegExp)[] } \| boolean	false	配置前后端打通，如果请求路径命中配置的origins，则会在请求头里补充x-rum-traceparent头，便于服务端监控串联整个链路。常用于前后端链路打通的场景，可以帮助排查请求耗时长的原因，具体定位请求性能瓶颈。详情请参见全链路场景接入。
extractUrl (版本 >= 2.5.0 **** )	(originalUrl: string) => string	-	自定义请求路径的生成规则，传入原始路径，返回值作为新的请求路径。常用于聚合RESTFUL请求路径。

配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    fetch: {
      autoWrap: false,
      collectBodyOnError: true,
    }
  },
  ...
})

性能监控相关插件

性能监控插件不是一个插件，而是由多个插件组成，配置也比较简单，主要是提供各个性能指标的开关。常规的使用场景是，在关闭某个指标后，使用SDK提供的sendCustomPerfMetric方法手动上报该性能指标。

Performance可配置字段说明

字段	类型	默认值	说明
fp	boolean	true	fp指标开关，常用于不上报对应指标。
fcp	boolean	true	fcp指标开关，常用于不上报对应指标。
fid	boolean	true	fid指标开关，常用于不上报对应指标。
mpfid	boolean	true	mpfid指标开关，常用于不上报对应指标。
lcp	boolean	true	lcp指标开关，常用于不上报对应指标。
cls	boolean	true	cls指标开关，常用于不上报对应指标。
longtask	boolean	true	longtask指标开关，常用于不上报对应指标。
timing	boolean	true	timing指标开关，常用于不上报对应指标。

Performance配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    performance: {
      fp: false,
    }
  },
  ...
})

FMP可配置字段说明

字段	类型	默认值	说明
renderType	string	CSR	指定当前页面的渲染类型。 CSR：以默认算法计算FMP。 SSR：不以默认算法计算FMP，而是使用FCP代替FMP。

字段

类型

默认值

说明

renderType

string

CSR

指定当前页面的渲染类型。

CSR：以默认算法计算FMP。
SSR：不以默认算法计算FMP，而是使用FCP代替FMP。

FMP配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    fmp: {
      renderType: 'SSR',
    }
  },
  ...
})

TTI插件

由于TTI的算法依赖请求，启动时机较早，所以独立为一个插件，并未开放配置项，但是可以配置为false，关闭此指标的计算。

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    tti: false
  },
  ...
})

白屏插件

白屏插件是默认不开启，需要您手动配置才会开启。插件中包含的截图能力是基于html2canvas二次开发的，额外增加了隐藏具体文本信息的开关能力。

可配置字段说明

字段	类型	默认值	说明
rootSelector	string	body	dom打分的根节点，支持querySelector语法。手动配置rootSelector为打分的根节点，准确定才更高。如果只想监控某个区域是否白屏，也可以配置为指定的区域节点。
autoDetect	boolean	true	是否自动开启白屏监测。如果不想开启自动监测，希望能够手动监测，可以将此字段设置为false，然后调用SDK提供的detectBlankScreen方法手动监测是否白屏。
threshold	number	1.5	dom打分的阈值。如果计算出来的分数小于阈值，则认为可能是白屏。
screenshot	boolean	true	是否自动上报当前页面的截屏图片。截屏一定程度上涉及安全隐私，但是能够帮助判定当前页面是否真的白屏。说明如果高度和宽度为0或者超过maximum canvas size，截屏图片base64会返回`"data:,"`。 maximum canvas size相关内容，具体请参见Maximum canvas size。
mask	boolean	false	对以下节点的内容进行数据脱敏： Text input Svg Img canvas @apmplus/web >= 2.0.0才支持配置此字段。如果页面存在数据隐私，可以启动该字段，效果如下图所示：
partialShot	boolean	false	部分节点截图。@apmplus/web >= 2.0.0才支持配置此字段。白屏时默认截屏为document.body，启动该字段后则只截屏传入的rootSelector。
quality	number	0.1	截屏图片清晰度，取值范围：0 ~ 1。@apmplus/web >= 2.0.0才支持配置此字段。如果您想获取更清晰的截屏信息，可以提高该字段取值。说明由于1:1截屏转码后的base64过大，默认已对原页面进行缩小。缩放公式：360 / window.innerWidth。更多关于截屏图片的清晰度，请参见Syntax。

配置示例

import browserClient  from '@apmplus/web'

browserClient('init', {
  ...
  plugins: {
    blankScreen: {
      rootSelector: '#app',
    }
  },
  ...
})

关闭插件

配置插件

PV插件

JS错误插件

面包屑插件

静态资源性能插件

静态资源错误插件

XHR监控插件

Fetch监控插件

性能监控相关插件

白屏插件