开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载本指南以 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 个接口类别符号作用函数getPerformance(app?)获取指定 FirebaseApp 对应的FirebasePerformance实例默认使用默认 app函数initializePerformance(app, settings?)初始化性能监控实例并注入可选配置只能调用一次函数trace(performance, name)创建一个新的自定义 Trace性能追踪实例接口FirebasePerformance性能监控服务接口暴露app与两个采集开关属性接口PerformanceSettings初始化时的配置对象含两个可选布尔开关接口PerformanceTraceTrace 实例接口含计时、指标metric与属性attribute操作这六个符号的完整签名如下源自 common/api-review/performance.api.mdimport { 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与initializePerformance2.1getPerformance(app?)——懒获取实例getPerformance用于获取某个 app 关联的性能监控实例。源码实现位于 packages/performance/src/index.tsexport function getPerformance( app: FirebaseApp getApp() ): FirebasePerformance { app getModularInstance(app); const provider _getProvider(app, performance); const perfInstance provider.getImmediate() as PerformanceController; return perfInstance; }关键行为app参数可选缺省时自动使用默认 FirebaseAppgetApp()内部通过firebase/component的 Provider 机制按需实例化服务若实例尚未初始化getPerformance会触发注册的工厂函数完成初始化详见下文 2.3 的工厂逻辑。2.2initializePerformance(app, settings?)——带配置初始化initializePerformance是带配置的初始化入口且只能调用一次packages/performance/src/index.tsexport 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 行包含三条硬性约束理解它们有助于排查性能监控不工作的问题必须是默认 appapp.name ! [DEFAULT]时抛出FB not default错误必须在浏览器环境typeof window undefined时抛出no window错误再次印证不支持 Node.js依赖 Installations 与 API 能力工厂会获取installations-internal依赖并调用setupApi(window)注入浏览器 APIpackages/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配置项类型默认值控制范围dataCollectionEnabledboolean?true是否采集自定义事件custom tracesinstrumentationEnabledboolean?true是否采集开箱即用事件自动 Trace 与 HTTP/S 网络监控默认值来自单例SettingsServicepackages/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中桥接到SettingsServicepackages/performance/src/controllers/perf.tsset instrumentationEnabled(val: boolean) { SettingsService.getInstance().instrumentationEnabled val; } set dataCollectionEnabled(val: boolean) { SettingsService.getInstance().dataCollectionEnabled val; }这两个开关的生效位置在日志层logTracepackages/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正是为此设计。四、自定义 Tracetrace()与PerformanceTrace4.1 创建 Tracetrace(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.tsstart()通过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.tsstartTime与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 自定义指标MetricputMetric/incrementMetric/getMetric方法语义说明putMetric(name, num)将指标设为指定值不存在则创建值会被向下取整为整数incrementMetric(name, num?)累加指标num缺省为 1不存在则按putMetric(name, num)创建getMetric(name)读取指标值不存在时返回 0t.putMetric(itemsLoaded, 42); t.incrementMetric(itemsLoaded); // 变为 43 t.incrementMetric(retries, 3); // 新建 retries3 const n t.getMetric(itemsLoaded); // 43实现要点incrementMetric的默认增量是 1packages/performance/src/resources/trace.ts指标名须通过isValidMetricName校验packages/performance/src/utils/metric_utils.ts长度 1100且不能以保留前缀_开头自动埋点的内置指标如_fcp、_lcp均以_开头属于保留命名空间值统一经convertMetricValueToInteger向下取整小数输入会打印 console 提示同文件第 62-69 行。4.4 自定义属性AttributeputAttribute/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规则约束属性名长度140 个字符属性名格式必须以字母开头仅含字母、数字、下划线^[a-zA-Z]\w*$属性名保留前缀不能以firebase_、google_、ga_开头避免与系统属性冲突属性值非空长度不超过 100 字符违反上述规则会分别抛出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)分三条队列启动页面加载 TracePage Load Trace监听pagehideSafari 兼容降级为unload与visibilitychange到 hidden 时通过Trace.createOobTrace生成一条名为_wt_页面路径的自动 Trace内置指标包括domInteractive、domContentLoadedEventEnd、loadEventEnd来自 Navigation Timing以及_fpFirst Paint、_fcpFirst Contentful Paint、_fidFirst Input Delay等实现见 packages/performance/src/resources/trace.ts指标常量见 packages/performance/src/constants.ts。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。网络请求监控遍历performance.getEntriesByType(resource)并通过PerformanceObserver持续监听将每个资源请求转换为NetworkRequestpackages/performance/src/resources/network_request.ts记录 URL去掉 query 部分、响应字节数、响应开始/完成耗时然后走logNetworkRequest上报。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 日志序列化与二次过滤logTracepackages/performance/src/services/perf_logger.ts在写入上报队列前还会做四重检查自动 Trace 且instrumentationEnabledfalse→ 丢弃自定义 Trace 且dataCollectionEnabledfalse→ 丢弃浏览器缺少必要 API → 丢弃若初始化Remote Config 拉取尚未完成则挂到getInitializationPromise上等初始化完成后再发送自定义 Trace 允许在初始化前创建。序列化后的日志格式serializeTrace同文件第 221-242 行包含trace_metricname、is_auto、client_start_time_us、duration_us、counters、custom_attributes与application_infogoogle_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.tsloggingEnabled默认 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.sendBeaconpayload 上限 64KBMAX_SEND_BEACON_PAYLOAD_SIZE失败则回退到fetchPOST第 137-154 行页面卸载时flushLogs()会强制冲刷队列每次最多 40 条logMaxFlushSize保证页面加载 Trace 优先送达第 183-211 行。七、常见错误速查SDK 通过firebase/util的ErrorFactory统一构造错误完整映射见 packages/performance/src/utils/errors.ts错误码触发场景trace started对已启动的 Trace 再次调用start()trace stopped对非 RUNNING 状态的 Trace 调用stop()nonpositive trace startTimerecord()传入非正 startTimenonpositive trace durationrecord()传入非正 durationno window非浏览器环境调用Node.js 等FB not default使用非默认 FirebaseApp 初始化性能监控invalid attribute name/invalid attribute value自定义属性名/值不满足长度或格式约束invalid custom metric name指标名超长或以保留前缀_开头already initialized以不同配置重复调用initializePerformance()八、版本与构建信息firebase/performance当前版本为0.7.14packages/performance/package.json依赖firebase/installations用于获取匿名实例 ID、web-vitalsWeb 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 与开关语义即可在浏览器应用中精确控制自定义与自动性能数据的采集范围。赞分享开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载相关推荐Firebase JS SDK 认证模块 firebase/auth 公共 API 完全指南从接口定义到源码实现Firebase JS SDK 认证模块 firebase/auth 公共 API 完全指南从接口定义到源码实现 common/api review/aut开发工具后端Firebase Performance性能监控实战Firebase Performance性能监控实战 概述 Firebase Performance Monitoring是Google Firebase提供的移动开发后端认证鉴权firebase-js-sdk 的 Firestore Litefirebase/firestore-lite公共 API 全面解析与实战指南firebase js sdk 的 Firestore Litefirebase/firestore lite公共 API 全面解析与实战指南 导读 本开发工具后端上一篇猫抓浏览器扩展三秒搞定网页视频下载的终极解决方案下一篇Cycle.js响应式数据聚合性能优化大数据集处理技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考