Firebase JS SDK 性能监控配置详解:PerformanceSettings 的 dataCollectionEnabled 与 instrumentationEnabled
Firebase JS SDK 性能监控配置详解:PerformanceSettings 的 dataCollectionEnabled 与 instrumentationEnabled
导读
本文围绕 Firebase JS SDK 中 Performance Monitoring(性能监控)的配置接口 PerformanceSettings 展开,深入解析其两个核心开关 —— dataCollectionEnabled 与 instrumentationEnabled 的作用范围、默认行为与底层生效机制。读完本文,你将掌握如何通过 initializePerformance() 在初始化阶段精确控制自定义 Trace 与自动监控数据的采集,理解两个开关在 SDK 源码中的实际过滤逻辑,并学会在运行时动态切换采集状态以应对隐私合规与流量控制场景。
PerformanceSettings 是什么
PerformanceSettings 是 Firebase Performance Monitoring Web SDK 的配置选项接口,定义在 packages/performance/src/public_types.ts 中,同时作为公开 API 从 docs-devsite/performance.performancesettings.md 对外发布。它通过 initializePerformance(app, settings) 的第二个可选参数传入,用于在 SDK 初始化阶段定制数据采集行为。
export interface PerformanceSettings {
/** Whether to collect custom events. */
dataCollectionEnabled?: boolean;
/** Whether to collect out of the box events. */
instrumentationEnabled?: boolean;
}
它与服务实例接口 FirebasePerformance 上的同名属性一一对应:PerformanceSettings 是「初始化时的一次性配置输入」,而 FirebasePerformance.dataCollectionEnabled / instrumentationEnabled 是「服务运行时的可读写状态」。两者的关系在 PerformanceController 的 _init() 方法中建立——初始化时传入的 settings 会被写入控制器,进而同步到全局的 SettingsService。
两个配置项:作用范围与取舍
| 属性 | 类型 | 是否必填 | 控制对象 | 默认值 |
|---|---|---|---|---|
dataCollectionEnabled |
boolean |
可选(?) |
自定义事件(custom traces)的上报 | true |
instrumentationEnabled |
boolean |
可选(?) |
开箱即用的自动事件(自动 trace 与 HTTP/S 网络监控)的上报 | true |
dataCollectionEnabled:自定义事件开关
该属性控制的是通过 SDK API 手动创建的自定义 Trace(custom traces)是否会被记录并上报。所谓"自定义事件",是指通过 trace(performance, name) 创建的 PerformanceTrace,配合 start() / stop() / record() / putMetric() 等 API 手动埋点的业务性能数据。
关闭它(false)意味着:即使代码中显式创建并启停 Trace,这些数据也不会进入上报流程。在源码层面,这一判断发生在 perf_logger.ts 的 logTrace() 中:
// Do not log if trace is custom and data collection is disabled.
if (!settingsService.dataCollectionEnabled && !trace.isAuto) {
return;
}
其中 trace.isAuto 标识 Trace 是否为自动创建:自定义 Trace 的 isAuto 默认为 false(见 trace.ts 构造函数),自动 Trace 则为 true。
instrumentationEnabled:开箱即用事件开关
该属性控制的是无需任何埋点代码即可自动采集的监控数据,包括:
- 页面加载 Trace(Page Load Trace,名称以
_wt_前缀开头,见 constants.ts); - Web Vitals 指标(LCP、CLS、INP 以及 FID,分别对应
_lcp、_cls、_inp、_fid计数器,见 constants.ts); - 通过
performance.mark()/performance.measure()用户 Timing API 产生的 measure 自动 Trace(见 oob_resources_service.ts); - 页面所有资源请求(HTTP/S 网络请求)的自动监控,包括请求时间、响应字节数、HTTP 响应码等(见 network_request.ts)。
这些数据由 SDK 初始化后自动挂载的观察器收集(见 setupOobResources),开发者无需任何额外操作。关闭该开关时,logTrace() 对自动 Trace 直接短路:
// Do not log if trace is auto generated and instrumentation is disabled.
if (!settingsService.instrumentationEnabled && trace.isAuto) {
return;
}
而网络请求的监控只受 instrumentationEnabled 一个开关约束,不受 dataCollectionEnabled 影响:
export function logNetworkRequest(networkRequest: NetworkRequest): void {
const settingsService = SettingsService.getInstance();
// Do not log network requests if instrumentation is disabled.
if (!settingsService.instrumentationEnabled) {
return;
}
...
}
需要特别指出的是,SDK 会对自身发往日志/传输端点的请求做黑名单过滤,避免自监控造成循环上报(见 perf_logger.ts),因此关闭自动监控不会影响 SDK 自身的网络请求。
何时关闭哪个开关
两个开关默认均为 true(见下文),实际使用中的典型场景:
- 隐私合规场景:产品不允许未经用户同意采集任何性能数据时,可在初始化时将两者同时置为
false,待用户授权后再通过运行时属性开启; - 只想用自动监控、不需要自定义埋点:置
dataCollectionEnabled: false,保留页面加载与网络监控; - 只想手动埋点、不想被自动采集干扰:置
instrumentationEnabled: false,仅保留trace()手动创建的 Trace; - 调试/降级场景:临时关闭全部采集以排查 SDK 上报链路问题。
默认值机制
两个配置项在接口上均为可选(?),因此不传时行为由 SDK 内置默认值决定。默认值定义在 settings_service.ts 的 SettingsService 单例中:
// The variable which controls logging of automatic traces and HTTP/S network monitoring.
instrumentationEnabled = true;
// The variable which controls logging of custom traces.
dataCollectionEnabled = true;
也就是说:默认情况下 SDK 同时采集自定义事件与开箱即用事件。PerformanceController._init() 采用"按需覆盖"策略——只有当 settings 中显式提供了某个属性时才覆盖默认值:
if (settings?.dataCollectionEnabled !== undefined) {
this.dataCollectionEnabled = settings.dataCollectionEnabled;
}
if (settings?.instrumentationEnabled !== undefined) {
this.instrumentationEnabled = settings.instrumentationEnabled;
}
因此 initializePerformance(app, {}) 与 initializePerformance(app) 在行为上完全等价,均保持默认采集开启状态。SettingsService 中还有一些由 Remote Config 远程下发控制的内部参数(如 loggingEnabled、tracesSamplingRate、networkRequestsSamplingRate、configTimeToLive = 12 小时缓存 TTL 等,见 remote_config_service.ts),它们与两个布尔开关叠加共同决定最终是否上报——即使两个开关都为 true,远程配置的采样率与总开关仍可能阻止某条数据被发送。
如何传入配置:initializePerformance 的初始化约束
配置通过模块级函数 initializePerformance(app, settings) 传入,其签名定义在 docs-devsite/performance.md 与 packages/performance/src/index.ts:
export declare function initializePerformance(
app: FirebaseApp,
settings?: PerformanceSettings
): FirebasePerformance;
典型用法:
import { initializeApp } from 'firebase/app';
import { initializePerformance, getPerformance, trace } from 'firebase/performance';
const app = initializeApp(firebaseConfig);
// 初始化阶段即关闭自动监控,仅保留自定义 Trace 采集
const perf = initializePerformance(app, {
dataCollectionEnabled: true,
instrumentationEnabled: false
});
// 之后创建自定义 Trace 不会受影响
const t = trace(perf, 'checkout-flow');
t.start();
// ... 业务逻辑
t.stop();
使用 initializePerformance 必须遵守以下约束(可从源码确认):
- 只能调用一次。该函数通过 provider 的
isInitialized()判断是否已初始化(index.ts):- 若已初始化且本次传入的 settings 与初始 settings 深度相等(
deepEqual),则直接返回既有实例,不报错; - 若 settings 不同,则抛出
ErrorCode.ALREADY_INITIALIZED错误(错误文案见 errors.ts)。
- 若已初始化且本次传入的 settings 与初始 settings 深度相等(
getPerformance()也会触发初始化。getPerformance(app)通过provider.getImmediate()获取实例;若先调用getPerformance()再调用initializePerformance(),同样会触发ALREADY_INITIALIZED逻辑,因此若需要传入自定义 settings,必须把initializePerformance()放在最前面。- 仅支持默认 app 实例。工厂函数中若
app.name !== '<a href="https://link.gitcode.com/i/0dbdd9d24d5a5dc738bac674a14e44a4" target="_blank">DEFAULT]'会抛出FB_NOT_DEFAULT错误([index.ts),即 Performance 只能挂载在默认 FirebaseApp 上。 - 仅浏览器环境可用。SDK 明确声明 "This SDK does not work in a Node.js environment"(见 docs-devsite/performance.md 与 packages/performance/src/index.ts),初始化时若
window不存在会抛出NO_WINDOW;且浏览器需支持Fetch、Promise并启用 Cookie,否则会输出提示信息而无法启动(perf.ts)。
运行时动态切换:FirebasePerformance 实例属性
采集开关并非"初始化定终身"。FirebasePerformance 实例上的两个属性带有 getter/setter,可直接读写全局 SettingsService 状态(perf.ts):
set instrumentationEnabled(val: boolean) {
SettingsService.getInstance().instrumentationEnabled = val;
}
get instrumentationEnabled(): boolean {
return SettingsService.getInstance().instrumentationEnabled;
}
dataCollectionEnabled 的 getter/setter 结构完全相同。因此可以在用户授权后动态开启采集:
import { getPerformance } from 'firebase/performance';
const perf = getPerformance(); // 使用默认 app 获取实例
// 用户同意隐私条款后开启采集
perf.dataCollectionEnabled = true;
perf.instrumentationEnabled = true;
// 或随时关闭
perf.instrumentationEnabled = false;
由于 logTrace() / logNetworkRequest() 在每次上报前都会实时读取 SettingsService 中的当前值,因此运行时切换即时生效,无需重新初始化或刷新页面。若初始化时已关闭采集,且后续在代码中直接调用 getPerformance()(而非 initializePerformance()),即可通过该实例属性重新打开。
底层生效链路与源码验证
两个开关的完整生效链路可归纳为:
initializePerformance(app, settings)
→ provider.initialize({ options: settings }) [index.ts]
→ factory 创建 PerformanceController [index.ts]
→ perfInstance._init(settings) [perf.ts]
→ 写入 SettingsService 单例 [settings_service.ts]
→ setupTransportService + 初始化 Promise + setupOobResources
→ Trace.stop()/record()/网络请求观察器触发
→ logTrace() / logNetworkRequest() 读取开关过滤 [perf_logger.ts]
→ 采样判断 → transportHandler 序列化并上报
关键过滤点集中在 perf_logger.ts:
logTrace(trace):instrumentationEnabled === false && trace.isAuto === true时跳过(自动 Trace);dataCollectionEnabled === false && trace.isAuto === false时跳过(自定义 Trace);logNetworkRequest(...):instrumentationEnabled === false时跳过(网络请求仅受自动监控开关控制)。
仓库的单元测试对上述行为有完整覆盖(perf.test.ts):
- "applies the settings if provided":传入
{ instrumentationEnabled: false, dataCollectionEnabled: false }后,断言控制器两个属性均为false; - "uses defaults when settings are not provided":不传 settings 时,断言与
SettingsService默认值一致(即true); - 四个属性读写用例分别验证
true/false两种状态的 setter/getter 行为。
使用建议与注意事项
- 版本与安装:本文所述行为对应当前仓库中
@firebase/performance0.7.x 版本(见 packages/performance/package.json)。该包不面向直接使用,官方推荐通过统一的firebase包引入(见 packages/performance/README.md),即import { initializePerformance } from 'firebase/performance'。 - 初始化顺序:需要自定义配置时,务必让
initializePerformance(app, settings)先于任何getPerformance()或trace()调用,避免触发ALREADY_INITIALIZED。 - 配置粒度:两个开关只控制"是否采集/上报",不控制远程配置层面的采样率;若需更细粒度控制,应结合 Firebase 控制台 Performance 的 Remote Config 设置。
- 自定义 Trace 的日志时机会延迟:从源码看,自定义 Trace 即使发生在初始化完成前,其日志也会等待初始化 Promise 完成后补发(perf_logger.ts),因此关闭开关的判断在最终上报时仍会生效。
- 网络请求字段:上报的网络请求 URL 会去除查询参数,且以微秒(us)为时间单位(network_request.ts),便于与后端日志字段对齐理解。
通过合理组合 dataCollectionEnabled 与 instrumentationEnabled,你可以在"自动监控的零埋点便利"与"自定义 Trace 的精准业务洞察"之间自由取舍,并在隐私合规与数据完整性之间取得平衡。