Firebase JavaScript SDK 性能监控模块（@firebase/performance）公共 API 完全指南

• 开发工具
• 后端

本指南以 firebase-js-sdk 仓库中@firebase/performance包的公开 API 报告（common/api-review/performance.api.md）为骨架，结合 packages/performance/src 下的核心源码与测试，系统讲解 Performance Monitoring Web SDK 的函数、接口、配置项与底层实现。读完本文，你将掌握如何初始化性能监控、配置数据采集开关、创建自定义 Trace，并理解自动埋点（页面加载、网络请求、Web Vitals）与日志上报的完整链路。

说明：本文面向浏览器环境。@firebase/performance明确指出不支持 Node.js 环境（见 packages/performance/src/index.ts），所有 API 均需在浏览器页面中运行。

一、API 概览：六个公共符号构成完整监控体系

API 报告文件列出了@firebase/performance的全部公共导出，共 3 个函数与 3 个接口：

这六个符号的完整签名如下（源自 common/api-review/performance.api.md）：

import { FirebaseApp } from '@firebase/app'; export interface FirebasePerformance { app: FirebaseApp; dataCollectionEnabled: boolean; instrumentationEnabled: boolean; } export function getPerformance(app?: FirebaseApp): FirebasePerformance; export function initializePerformance(app: FirebaseApp, settings?: PerformanceSettings): FirebasePerformance; export interface PerformanceSettings { dataCollectionEnabled?: boolean; instrumentationEnabled?: boolean; } export interface PerformanceTrace { getAttribute(attr: string): string | undefined; getAttributes(): { [key: string]: string }; getMetric(metricName: string): number; incrementMetric(metricName: string, num?: number): void; putAttribute(attr: string, value: string): void; putMetric(metricName: string, num: number): void; record(startTime: number, duration: number, options?: { metrics?: { [key: string]: number }; attributes?: { [key: string]: string }; }): void; removeAttribute(attr: string): void; start(): void; stop(): void; } export function trace(performance: FirebasePerformance, name: string): PerformanceTrace;

二、初始化：getPerformance与initializePerformance

2.1getPerformance(app?)——懒获取实例

getPerformance用于获取某个 app 关联的性能监控实例。源码实现位于 packages/performance/src/index.ts：

export function getPerformance( app: FirebaseApp = getApp() ): FirebasePerformance { app = getModularInstance(app); const provider = _getProvider(app, 'performance'); const perfInstance = provider.getImmediate() as PerformanceController; return perfInstance; }

关键行为：

• app参数可选，缺省时自动使用默认 FirebaseApp（getApp()）；
• 内部通过@firebase/component的 Provider 机制按需实例化服务；
• 若实例尚未初始化，getPerformance会触发注册的工厂函数完成初始化（详见下文 2.3 的工厂逻辑）。

2.2initializePerformance(app, settings?)——带配置初始化

initializePerformance是带配置的初始化入口，且只能调用一次（packages/performance/src/index.ts）：

export function initializePerformance( app: FirebaseApp, settings?: PerformanceSettings ): FirebasePerformance { app = getModularInstance(app); const provider = _getProvider(app, 'performance'); // throw if an instance was already created. // It could happen if initializePerformance() is called more than once, or getPerformance() is called first. if (provider.isInitialized()) { const existingInstance = provider.getImmediate(); const initialSettings = provider.getOptions() as PerformanceSettings; if (deepEqual(initialSettings, settings ?? {})) { return existingInstance; } else { throw ERROR_FACTORY.create(ErrorCode.ALREADY_INITIALIZED); } } const perfInstance = provider.initialize({ options: settings }) as PerformanceController; return perfInstance; }

注意这里的幂等性设计：

• 若实例已存在且传入配置与原配置完全相同（通过deepEqual比较），直接返回既有实例，不会报错；
• 若配置不同，则抛出already initialized错误（错误码定义见 packages/performance/src/utils/errors.ts），错误信息提示开发者应使用与首次调用相同的配置，或改用getPerformance()获取已初始化实例。

2.3 服务注册与工厂初始化条件

性能服务通过模块加载时自动调用registerPerformance()完成注册（packages/performance/src/index.ts）。实例工厂（第 112-133 行）包含三条硬性约束，理解它们有助于排查"性能监控不工作"的问题：

1. 必须是默认 app：app.name !== '[DEFAULT]'时抛出FB not default错误；
2. 必须在浏览器环境：typeof window === 'undefined'时抛出no window错误（再次印证不支持 Node.js）；
3. 依赖 Installations 与 API 能力：工厂会获取installations-internal依赖并调用setupApi(window)注入浏览器 API（packages/performance/src/services/api_service.ts）。

初始化完成后，PerformanceController._init(settings)会应用传入的配置并异步启动底层服务（packages/performance/src/controllers/perf.ts），只有浏览器支持 Fetch、Promise 且 Cookie 可用（requiredApisAvailable()）时才会真正启动；否则仅打印一条 console 提示。

三、配置项详解：PerformanceSettings与两个开关

PerformanceSettings接口只有两个可选布尔字段（packages/performance/src/public_types.ts）：

默认值来自单例SettingsService（packages/performance/src/services/settings_service.ts）：

// 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;

运行时也可通过FirebasePerformance实例的属性动态切换（对应接口定义见 packages/performance/src/public_types.ts），这两个属性在PerformanceController中桥接到SettingsService（packages/performance/src/controllers/perf.ts）：

set instrumentationEnabled(val: boolean) { SettingsService.getInstance().instrumentationEnabled = val; } set dataCollectionEnabled(val: boolean) { SettingsService.getInstance().dataCollectionEnabled = val; }

这两个开关的生效位置在日志层logTrace（packages/performance/src/services/perf_logger.ts）：自动 Trace 在instrumentationEnabled为 false 时被丢弃；自定义 Trace 在dataCollectionEnabled为 false 时被丢弃。

3.1 初始化示例

import { initializeApp } from '@firebase/app'; import { getPerformance, initializePerformance } from '@firebase/performance'; const app = initializeApp(firebaseConfig); // 方式一：不传配置，直接获取实例 const perf = getPerformance(app); // 方式二：带配置初始化（只能调用一次） const perf2 = initializePerformance(app, { dataCollectionEnabled: true, // 采集自定义 Trace instrumentationEnabled: false // 关闭自动埋点（页面加载 / 网络请求） });

若你的业务只需要自定义 Trace 而想关闭自动埋点，instrumentationEnabled: false正是为此设计。

四、自定义 Trace：trace()与PerformanceTrace

4.1 创建 Trace

trace(performance, name)工厂函数（packages/performance/src/index.ts）返回一个Trace实例，其实现类位于 packages/performance/src/resources/trace.ts。Trace内部维护一个状态机（UNINITIALIZED→RUNNING→TERMINATED），非法调用会抛错。

4.2 计时：start()/stop()/record()

start/stop 模式适用于可以包裹在代码执行前后的场景：

const t = trace(getPerformance(), 'checkout-flow'); t.start(); // 开始计时 // ... 执行业务逻辑（如结算流程） t.stop(); // 停止计时并立即记录日志

底层实现（packages/performance/src/resources/trace.ts）：

• start()通过performance.mark()打上以FB-PERF-TRACE-START为前缀的 User Timing 标记（前缀常量见 packages/performance/src/constants.ts），重复 start 会抛出trace started错误；
• stop()打停止标记、调用performance.measure()计算耗时，再由calculateTraceMetrics()从 Performance Timeline 读取时长（微秒级durationUs），最后交给logTrace上报。

record 模式适用于耗时信息先于 SDK 加载捕获、无法包裹代码的场景，直接给出起止时间：

t.record(startTime, duration, { metrics: { itemCount: 3 }, attributes: { experiment: 'v2' } });

record()的参数校验与行为（packages/performance/src/resources/trace.ts）：

• startTime与duration必须为正数，否则分别抛出nonpositive trace startTime/nonpositive trace duration错误；
• 时间单位为毫秒，内部会乘以 1000 转换为微秒并向下取整；
• metrics中非数值项会被静默忽略；
• 调用后立即logTrace，无需再调stop()。

测试用例 packages/performance/src/resources/trace.test.ts 验证了record(0, 20)、record(-100, 20)等非法输入会抛错，且record(1, 20, { metrics: { cacheHits: 1 } })后getMetric('cacheHits')返回 1。

4.3 自定义指标（Metric）：putMetric/incrementMetric/getMetric

t.putMetric('itemsLoaded', 42); t.incrementMetric('itemsLoaded'); // 变为 43 t.incrementMetric('retries', 3); // 新建 retries=3 const n = t.getMetric('itemsLoaded'); // 43

实现要点：

• incrementMetric的默认增量是 1（packages/performance/src/resources/trace.ts）；
• 指标名须通过isValidMetricName校验（packages/performance/src/utils/metric_utils.ts）：长度 1～100，且不能以保留前缀_开头（自动埋点的内置指标如_fcp、_lcp均以_开头，属于保留命名空间）；
• 值统一经convertMetricValueToInteger向下取整，小数输入会打印 console 提示（同文件第 62-69 行）。

4.4 自定义属性（Attribute）：putAttribute/getAttribute/removeAttribute/getAttributes

属性用于给 Trace 附加维度信息（如实验分组、用户层级），便于在 Firebase 控制台分组分析：

t.putAttribute('experiment', 'v2'); const v = t.getAttribute('experiment'); // 'v2' t.removeAttribute('experiment'); const all = t.getAttributes(); // 当前全部属性的副本

校验规则来自 packages/performance/src/utils/attributes_utils.ts：

违反上述规则会分别抛出invalid attribute name/invalid attribute value错误（packages/performance/src/utils/errors.ts）。

五、开箱即用的自动埋点（Out-of-the-Box 资源）

当instrumentationEnabled为 true 时，SDK 会自动采集三类资源，全部由 packages/performance/src/services/oob_resources_service.ts 在初始化后通过setTimeout(0)分三条队列启动：

1. 页面加载 Trace（Page Load Trace）：监听pagehide（Safari 兼容降级为unload）与visibilitychange到 hidden 时，通过Trace.createOobTrace生成一条名为_wt_<页面路径>的自动 Trace，内置指标包括domInteractive、domContentLoadedEventEnd、loadEventEnd（来自 Navigation Timing），以及_fp（First Paint）、_fcp（First Contentful Paint）、_fid（First Input Delay）等（实现见 packages/performance/src/resources/trace.ts，指标常量见 packages/performance/src/constants.ts）。
2. Web Vitals 采集：借助web-vitals/attribution库监听 LCP、CLS、INP，以_lcp、_cls、_inp指标上报，并附带lcp_element、cls_largestShiftTarget、inp_interactionTarget属性说明归因元素（packages/performance/src/services/oob_resources_service.ts）。
3. 网络请求监控：遍历performance.getEntriesByType('resource')并通过PerformanceObserver持续监听，将每个资源请求转换为NetworkRequest（packages/performance/src/resources/network_request.ts），记录 URL（去掉 query 部分）、响应字节数、响应开始/完成耗时，然后走logNetworkRequest上报。
4. User Timing 透传：监听页面中的performance.measure()条目，自动将开发者自定义的 User Timing measure 转成 Trace 上报（createUserTimingTrace），前提是该 measure 名不是 SDK 自身的FB-PERF-TRACE-MEASURE前缀（packages/performance/src/services/oob_resources_service.ts）。

六、数据上报链路：采样、批处理与传输

理解 Trace 从采集到入库的链路，能帮助你判断数据为何"没有上报"。

6.1 日志序列化与二次过滤

logTrace（packages/performance/src/services/perf_logger.ts）在写入上报队列前还会做四重检查：

1. 自动 Trace 且instrumentationEnabled=false→ 丢弃；
2. 自定义 Trace 且dataCollectionEnabled=false→ 丢弃；
3. 浏览器缺少必要 API → 丢弃；
4. 若初始化（Remote Config 拉取）尚未完成，则挂到getInitializationPromise上等初始化完成后再发送（自定义 Trace 允许在初始化前创建）。

序列化后的日志格式（serializeTrace，同文件第 221-242 行）包含trace_metric（name、is_auto、client_start_time_us、duration_us、counters、custom_attributes）与application_info（google_app_id、app_instance_id、sdk_version、page_url、service_worker_status、visibility_state、effective_connection_type 等环境维度）。

6.2 采样与开关（Remote Config 驱动）

SettingsService中有两组与服务端配置相关的字段（packages/performance/src/services/settings_service.ts）：loggingEnabled（默认 false，由 Remote Config 下发）、tracesSamplingRate与networkRequestsSamplingRate（默认 1，即全量采样）、logTraceAfterSampling等。sendTraceLog只有loggingEnabled && logTraceAfterSampling同时为真才真正发送。SDK 启动时会从 Remote Config 拉取fpr_enabled、fpr_vc_trace_sampling_rate、fpr_log_max_flush_size等参数（packages/performance/src/services/remote_config_service.ts），配置默认缓存 12 小时（configTimeToLive = 12），并存于 localStorage（键为@firebase/performance/config）。

6.3 传输：批处理队列 + sendBeacon/fetch 双通道

packages/performance/src/services/transport_service.ts 实现了传输层：

• 初始化后约 5.5 秒（INITIAL_SEND_TIME_DELAY_MS）首次尝试发送，之后每 10 秒（DEFAULT_SEND_INTERVAL_MS）轮询队列（第 78-90 行）；
• 单次请求最多携带 1000 条事件（MAX_EVENT_COUNT_PER_REQUEST），发送失败会将事件回插队列并重试，最多 3 次（DEFAULT_REMAINING_TRIES）；
• 优先使用navigator.sendBeacon（payload 上限 64KB，MAX_SEND_BEACON_PAYLOAD_SIZE），失败则回退到fetchPOST（第 137-154 行）；
• 页面卸载时flushLogs()会强制冲刷队列（每次最多 40 条，logMaxFlushSize），保证页面加载 Trace 优先送达（第 183-211 行）。

七、常见错误速查

SDK 通过@firebase/util的ErrorFactory统一构造错误（完整映射见 packages/performance/src/utils/errors.ts）：

八、版本与构建信息

@firebase/performance当前版本为0.7.14（packages/performance/package.json），依赖@firebase/installations（用于获取匿名实例 ID）、web-vitals（Web Vitals 采集）、@firebase/logger与@firebase/util；以@firebase/app为 peerDependency。该包不面向直接使用，官方推荐通过firebase聚合包使用（见 packages/performance/README.md），其 API 报告由 API Extractor 自动生成并作为发布门禁（yarn api-report，见 package.json 的 scripts）。

结语

通过 common/api-review/performance.api.md 这份 API 报告，我们完整梳理了 Firebase Performance Monitoring Web SDK 的六个公共符号：两个初始化函数（getPerformance/initializePerformance）、一个 Trace 工厂（trace）、一个配置接口（PerformanceSettings）与两个服务接口（FirebasePerformance/PerformanceTrace）。结合 packages/performance/src 的源码可以看到，每个公共 API 背后都有清晰的实现边界：状态机保障 Trace 生命周期合法性，attributes_utils/metric_utils执行命名校验，perf_logger与transport_service完成采样与批量上报。掌握这些 API 与开关语义，即可在浏览器应用中精确控制自定义与自动性能数据的采集范围。

• 开发工具
• 后端