在 2024 年演示日活动中，观看有关如何使用 Firebase 构建和运行 AI 赋能应用的演示。立即观看。

Performance Monitoring 问题排查和常见问题解答

本页面提供了有关开始使用 Performance Monitoring 或者使用 Performance Monitoring 功能和工具的问题排查提示。

排查问题前的首要检查

作为最佳实践，在进一步排查问题之前，建议您先执行以下两项检查。

1. 检查日志消息中是否有性能事件

检查您的日志消息，确保 Performance Monitoring SDK 正在捕获性能事件。

如何查看日志消息中的性能事件

您可以在构建时为 Performance Monitoring 启用调试日志记录功能，方法是在应用的 AndroidManifest.xml 文件中添加 <meta-data> 元素，如下所示：
```
<application>
    <meta-data
      android:name="firebase_performance_logcat_enabled"
      android:value="true" />
</application>
```
检查您的日志消息中是否有错误消息。
Performance Monitoring 会使用 FirebasePerformance 标记其日志消息。借助 logcat 过滤功能，您可以运行以下命令来专门查看时长跟踪记录和 HTTP/HTTPS 网络请求日志记录：
```
adb logcat -s FirebasePerformance
```
检查以下类型的日志，这些日志表明 Performance Monitoring 正在记录性能事件：
- Logging trace metric: TRACE_NAME, FIREBASE_PERFORMANCE_CONSOLE_URL
- Logging network request trace: URL
点击网址即可在 Firebase 控制台中查看您的数据。系统可能需要一些时间才能在信息中心内更新数据。

如果您的应用未记录性能事件，请查看问题排查提示。

2. 查看 Firebase 状态信息中心

检查 Firebase 状态信息中心，确定是否存在已知的 Firebase 或 Performance Monitoring 服务中断。

Performance Monitoring 使用入门

如果您刚开始使用 Performance Monitoring (iOS+ | Android | Web)，以下问题排查提示可帮助您解决在 Firebase 检测 SDK 或在 Firebase 控制台中显示您的第一组性能数据时发生的问题。

已将 SDK 添加到应用，但控制台仍要求添加 SDK

Firebase 可以通过接收来自应用的事件信息（如应用交互）来检测 Performance Monitoring SDK 是否已成功添加到您的应用。通常，在启动应用后的 10 分钟内，Firebase 控制台的“性能”信息中心就会显示“已检测到 SDK”消息。之后，信息中心会在 30 分钟内显示最初经过处理的数据。

如果在添加最新版 SDK 10 分钟后仍然未看到任何变化，请检查您的日志消息以确保 Performance Monitoring 正在记录事件。请按照下文所述的相应问题排查步骤进行操作，排查 SDK 检测消息延迟的问题。

应用正在记录事件：问题排查步骤

请参阅版本说明，确保您使用的是 Performance Monitoring Android SDK 19.1.0 或更高版本（或 Firebase BoM 26.3.0 或更高版本）。
如果您仍在本地进行开发，请尝试生成更多事件以便收集数据：
1. 生成事件的方法包括：将应用在后台和前台之间切换数次、通过跨屏幕导航与应用进行交互，以及触发网络请求。
确保您的 Firebase 配置文件 (google-services.json) 已正确添加到您的应用，并且您没有修改过该文件。具体来说，请检查以下内容：
- 配置文件名未附加其他字符，如 (2)。
- 配置文件位于应用的模块（应用级）目录中。
- 您的应用的配置文件中列出的 Firebase Android 应用 ID (mobilesdk_app_id) 正确无误。您可以在 项目设置的“您的应用”卡片中找到 Firebase 应用 ID。
如果您的应用中的配置文件看似有误，请尝试以下操作：
1. 删除应用中当前存在的配置文件。
2. 按照这些说明下载新的配置文件并将其添加到您的 Android 应用。
如果 SDK 正在记录事件，并且一切设置均正确，但 10 分钟后，您仍未看到 SDK 检测消息或已处理的数据，请与 Firebase 支持团队联系。

应用未记录事件：问题排查步骤

检查 Performance Monitoring Gradle 插件的设置，如下所示：
1. 请确保您已正确添加插件。具体来说，请检查以下内容：
  - 您已在模块（应用级） build.gradle 文件中添加了插件 (apply plugin: 'com.google.firebase.firebase-perf')。
  - 您已在项目级 build.gradle 文件中添加了插件的类路径依赖项 (classpath 'com.google.firebase:perf-plugin:1.4.2')。
2. 检查以下任一标志，确保插件未停用：
  - 您的模块（应用级）build.gradle 文件中的 instrumentationEnabled
  - 您的 gradle.properties 文件中的 firebasePerformanceInstrumentationEnabled
检查您的 AndroidManifest.xml 文件中的以下任一标志，确保 Performance Monitoring SDK 未停用：
- firebase_performance_collection_enabled
- firebase_performance_collection_deactivated
确保 Performance Monitoring 在运行时未停用。
如果您在应用中未找到任何停用的内容，请与 Firebase 支持团队联系。

控制台显示已检测到 SDK，但未显示任何数据

Performance Monitoring 会先处理性能事件数据，然后再将其显示在“性能”信息中心中。

如果距“检测到了 SDK”消息出现已超过 24 小时，但您仍然看不到数据，请查看 Firebase 状态信息中心是否存在已知的中断。如果没有中断，请与 Firebase 支持团队联系。

常规问题排查

如果您已成功添加 SDK 并在应用中使用 Performance Monitoring，以下问题排查提示可帮助解决关于 Performance Monitoring 功能和工具的常规问题。

应用未记录性能事件

如果您没有看到性能事件的日志消息，请尝试执行以下问题排查步骤：

检查 Performance Monitoring Gradle 插件的设置，如下所示：
1. 请确保您已正确添加插件。具体来说，请检查以下内容：
  - 您已在模块（应用级） build.gradle 文件中添加了插件 (apply plugin: 'com.google.firebase.firebase-perf')。
  - 您已在项目级 build.gradle 文件中添加了插件的类路径依赖项 (classpath 'com.google.firebase:perf-plugin:1.4.2')。
2. 检查以下任一标志，确保插件未停用：
  - 您的模块（应用级）build.gradle 文件中的 instrumentationEnabled
  - 您的 gradle.properties 文件中的 firebasePerformanceInstrumentationEnabled
检查您的 AndroidManifest.xml 文件中的以下任一标志，确保 Performance Monitoring SDK 未停用：
- firebase_performance_collection_enabled
- firebase_performance_collection_deactivated
确保 Performance Monitoring 在运行时未停用。
如果您在应用中未找到任何停用的内容，请与 Firebase 支持团队联系。

性能信息中心缺少屏幕跟踪记录数据

如果缺少屏幕渲染跟踪记录的数据，请尝试执行以下问题排查步骤：

确保您使用的是最新版 Android SDK (v21.0.3)。仅在 v15.2.0 或更高版本中支持屏幕渲染跟踪记录功能。
确保您没有为屏幕手动停用硬件加速。
确保您未使用 DexGuard 或 Jack。Performance Monitoring 与这些工具链不兼容。
- DexGuard 会停用自动收集应用启动、应用前台活动和应用后台活动跟踪记录的功能。但是，如果您的应用使用 DexGuard，任何自定义代码跟踪记录都应该不受影响。
- Jack 已被弃用，通常不应在应用中使用。

性能信息中心缺少自定义跟踪记录数据

您看到了自动收集的跟踪记录的性能数据，但没有看到自定义代码跟踪记录的性能数据？请尝试执行以下问题排查步骤：

如果您通过 Trace API 对自定义跟踪记录进行插桩，请检查跟踪记录的设置，尤其是以下内容：
- 自定义代码跟踪记录和自定义指标的名称必须符合以下要求：没有前导空格或尾随空格，没有前导下划线 (_) 字符，长度上限为 32 个字符。
- 所有跟踪记录都必须有开始和停止。任何未开始、未停止或在开始前停止的跟踪记录都不会被记入日志。
如果您通过 @AddTrace 注释对自定义代码跟踪记录进行插桩，请检查 Performance Monitoring Gradle 插件的设置：
1. 请确保您已正确添加插件。具体来说，请检查以下内容：
  - 您已在模块（应用级） build.gradle 文件中添加了插件 (apply plugin: 'com.google.firebase.firebase-perf')。
  - 您已在项目级 build.gradle 文件中添加了插件的类路径依赖项 (classpath 'com.google.firebase:perf-plugin:1.4.2')。
2. 检查以下任一标志，确保插件未停用：
  - 您的模块（应用级）build.gradle 文件中的 instrumentationEnabled
  - 您的 gradle.properties 文件中的 firebasePerformanceInstrumentationEnabled
检查您的日志消息，确保 Performance Monitoring 正在记录预期的自定义代码跟踪记录。
如果 Performance Monitoring 正在记录事件，但 24 小时后未显示任何数据，请与 Firebase 支持团队联系。

性能信息中心缺少网络请求数据

如果缺少网络请求数据，请尝试执行以下问题排查步骤：

对于 Android 应用，Performance Monitoring Gradle 插件会启用插桩，以实现自动 HTTP/S 网络请求监控。请检查以下各项：
1. 请确保您已正确添加插件。具体来说，请检查以下内容：
  - 您已在模块（应用级） build.gradle 文件中添加了插件 (apply plugin: 'com.google.firebase.firebase-perf')。
  - 您已在项目级 build.gradle 文件中添加了插件的类路径依赖项 (classpath 'com.google.firebase:perf-plugin:1.4.2')。
2. 检查以下任一标志，确保插件未停用：
  - 您的模块（应用级）build.gradle 文件中的 instrumentationEnabled
  - 您的 gradle.properties 文件中的 firebasePerformanceInstrumentationEnabled
检查网络库兼容性。Performance Monitoring 会自动收集使用以下网络库的网络请求的指标：OkHttp 3.x.x、Java 的 URLConnection 以及 Apache HttpClient。

请注意，您可以为网络请求添加自定义监控功能。
请注意以下事项：
- Performance Monitoring 可能只会报告已完成的网络请求，具体取决于您的代码的行为以及代码所使用的网络库。这意味着，报告中可能不会显示未完成的 HTTP/HTTPS 连接。
- Performance Monitoring 与 DexGuard 和 Jack 不兼容。
  - DexGuard 会停用对 HTTP/HTTPS 网络请求的监控。
  - Jack 已被弃用，通常不应在应用中使用。
- Performance Monitoring 不会报告 Content-Type 标头无效的网络请求。但是，系统仍会接受不含 Content-Type 标头的网络请求。

网络请求数据未按预期汇总

详细了解 Performance Monitoring 如何在网址格式下汇总网络请求数据。

您也可以尝试使用自定义网址格式。

常见问题解答

“项目”首页上的“性能”卡片中的“常见问题”发生了什么变化？

我们近期推出了提醒功能（该功能会在相应指标超过您设置的阈值时自动通知您），随后将常见问题替换为近期提醒。问题现已弃用，并替换为提醒。

“性能”卡片顶部的应用选择器会过滤近期提醒下的提醒条目。系统仅显示与所选应用有关的三项最新提醒。

如需详细了解提醒，请参阅针对性能问题设置提醒。

在控制台中为问题设置阈值的功能发生了什么变化？

Performance Monitoring 支持为超出定义阈值的指标发出提醒。为避免与这些可配置的性能指标阈值混淆，我们移除了为问题配置阈值的功能。

Firebase 控制台中的“详细信息”和“指标”信息发生了什么变化？

我们已将“详细信息”和“指标”页面替换为重新设计的集中式界面 (UI)，以改进您排查问题的方式。这一新的问题排查界面提供的核心功能与“详细信息”和“指标”提供的核心功能相同。如需详细了解如何排查问题，请参阅查看特定跟踪记录的更多数据。

为什么样本数量不符合预期？

Performance Monitoring 会从您应用的用户设备收集性能数据。如果您的应用有许多用户，或者应用生成大量性能活动，Performance Monitoring 可能会将数据收集的范围限定为一部分设备，以减少已处理的事件数量。这些限制足够高，因此即使事件较少，指标值仍然能代表用户的应用体验。

为了管理我们收集的数据量，Performance Monitoring 使用以下采样选项：

设备端速率限制：为了防止设备突然发送大量跟踪记录，我们将从一台设备发送的代码和网络请求跟踪记录的数量限制为每 10 分钟最多 300 个事件。此方法可以保护设备免受可能发送大量性能数据的循环插桩的影响，并且可防止个别设备导致性能衡量结果出现偏差。
动态采样：对于所有应用用户的每个应用，Performance Monitoring 每天会分别收集有限数量的代码跟踪记录和网络请求跟踪记录。系统会从设备上获取动态采样率（使用 Firebase Remote Config），以确定任一台随机设备是否应捕获和发送跟踪记录。如果设备未被选择用于采样，则不会发送任何事件。动态采样率因应用而异，并且经过调整，以确保已收集的数据总量保持在限额之内。

启用了 BigQuery 集成的项目的网络请求跟踪记录数量上限更高。

用户会话从用户设备发送额外的详细数据，需要更多资源来捕获和发送数据。为了最大限度地降低用户会话的影响，Performance Monitoring 可能还会限制会话数量。
服务器端速率限制：为确保应用不超出采样限制，Performance Monitoring 可能会使用服务器端采样来删除设备发送的部分事件。虽然这种限制不会改变指标的有效性，但可能会导致细微的模式变化，包括：
- 跟踪记录的数量可能与一段代码的执行次数不同。
- 代码中紧密耦合的跟踪记录可能各自具有不同数量的样本。

控制台中的“问题”标签页有何变化？

我们将“问题”标签页替换为“提醒”标签页，它会在超出您设置的阈值时自动通知您。您不再需要手动查看 Firebase 控制台来确定是否超过了阈值。要了解提醒，请参阅针对性能问题设置提醒。

控制台中的“设备上”和“网络”标签页有何变化？如何查看这些页面上的跟踪记录？

我们重新设计了 Firebase 控制台的 Performance Monitoring 部分，使得“信息中心”标签页在一个位置显示关键指标和您的所有跟踪记录。在重新设计过程中，我们移除了“设备上”和“网络”页面。

“信息中心”标签页底部的跟踪记录表包含“设备上”和“网络”标签页上显示的所有信息，但新增了一些功能，包括按特定指标的百分比变化对跟踪记录进行排序。如需查看特定跟踪记录的所有指标和数据，请点击跟踪记录表中的跟踪记录名称。

在跟踪记录表的以下子标签页中查看跟踪记录：

网络请求跟踪记录（开箱即用和自定义）- “网络请求”子标签
自定义代码跟踪记录 - “自定义跟踪记录”子标签
应用启动、应用前台活动、应用后台活动跟踪记录 - “自定义跟踪记录”子标签
屏幕呈现跟踪记录 - “屏幕呈现”子标签页
网页加载跟踪记录 - “网页加载”子标签

如需详细了解跟踪记录表并查看指标和数据，请访问控制台概览页面 (iOS+ | Android | Web)。

为什么呈现速度缓慢的帧和冻结的帧的数量不符合预期？

系统在计算呈现速度缓慢的帧和冻结的帧时会假定设备刷新频率为 60Hz。如果实际的设备刷新频率低于 60Hz，则每帧的呈现速度会更缓慢，因为每秒呈现的帧数会更少。如果呈现速度更缓慢，由于有更多帧会呈现得更慢或冻结，因此可能会导致系统报告的呈现速度缓慢的帧或冻结的帧的数量增加。不过，如果设备刷新频率高于 60Hz，那么每帧的呈现速度也会相应地更快；这也会减少系统报告的呈现速度缓慢的帧或冻结的帧的数量。这是 Performance Monitoring SDK 中的一项当前限制。

为什么我看不到 fragment 跟踪记录？

除了应用活动以外，如需查看 fragment 的性能，请确保您的应用使用的是 Performance Monitoring Android SDK 20.1.0 或更高版本。如需了解详情，请参阅将 Performance Monitoring 添加到您的应用。

如何了解哪些跟踪记录与 fragment 和 activity 相关？

每条 fragment 和 activity 跟踪记录都基于您的应用中定义的其类名称。每条屏幕跟踪记录都包含 st 前缀，后跟类名称。在 Firebase 控制台中，系统会移除该前缀。如需了解详情，请参阅了解屏幕呈现性能数据（Apple 和 Android 应用）。

为什么我看到的 fragment 跟踪记录少于其他跟踪记录？

Performance Monitoring 会对设备上收集的所有事件进行事件采样。通过这种方法，我们可以从用户设备收集提供性能指标所需的最少事件。

如果应用的呈现性能存在问题，系统如何通知我？

借助 Performance Monitoring，您可以针对自己关注的指标设置提醒。对于生成的屏幕呈现跟踪记录，您可以设置提醒，以便在慢帧和冻结的帧百分比超过您设置的阈值时收到通知。

启用 Performance Monitoring Gradle 插件后，我的构建时间变长了。如何改善这种情况？

Android 版 Performance Monitoring 使用字节码插桩来提供一些开箱即用的功能，例如监控 HTTP/HTTPS 网络请求。作为编译的一个环节，该过程需要迭代应用的所有类（包括依赖项），以便向对衡量应用的网络请求性能至关重要的代码插桩。

以下是造成构建时间延长的一些关键因素：

类或文件的数量
其中每个类（代码行）的大小
您的机器配置
初始构建与后续构建（后续构建通常比初始构建速度更快）

为了缩短构建时间，请考虑将您的代码模块化。

从 Performance Monitoring 插件的 v1.3.3 开始，我们一直专注于对库输入的增量构建处理和缓存进行重大改进。如需获得最新的构建时间方面的改进，请确保使用最新版本的插件 (v1.4.2)。

请注意，如果您希望避免构建时间过长，可以在本地为调试 build 停用 Performance Monitoring 插件。但是，建议不要对正式版 build 使用该方法，因为这样可能会导致您应用中的网络请求的性能测量结果缺失。

如果由于库与 Performance Monitoring Gradle 插件不兼容而导致发生构建错误，我该怎么办？

如果您在与 Performance Monitoring 插件集成后遇到构建错误（例如“JSR/RET are not supported with computeFrames option”或类似错误），这可能是因为您还依赖于一个与 Performance Monitoring Gradle 插件不兼容的库。

如需解决此问题，您可以按照以下步骤将不兼容的类/库排除在插桩之外：

更新到 Performance Monitoring Gradle 插件的最新版本（最低 v1.4.0）。
将您的 Android Gradle 插件版本更新到 v7.2.0 或更高版本。
将以下标志添加到您的模块（应用级）build.gradle 文件中，以便将不兼容的类/库排除在插桩之外：
```
android {
  // ...
  androidComponents {
    onVariants(selector().all(), {
        instrumentation.excludes.add("example.incompatible.library")
    })
  }
}
```
如需详细了解 Android Gradle 插件的 Instrumentation API 的 exclude 属性，请参阅插桩。

如果您因为库不兼容而遇到构建错误，请提交 GitHub 问题，以便系统在 Performance Monitoring 插件中也将这些库排除在插桩之外。

将 Performance Monitoring 数据导出到 BigQuery 所花的时间超出预期。性能数据不是实时的吗？

如果您已为 Firebase Performance Monitoring 启用了 BigQuery 集成，您的数据将在当天结束（太平洋时间）后 12 到 24 小时内导出至 BigQuery。

例如，4 月 19 日的数据将在 4 月 20 日中午 12 点到午夜（所有日期和时间均为太平洋时间）之间导出至 BigQuery。

近乎实时地处理和显示数据

“近乎实时”的性能数据是什么意思？

Firebase Performance Monitoring 会对收集到的性能数据进行即时处理，从而在 Firebase 控制台中近乎实时地显示数据。已处理的数据会在几分钟内（从收集数据时开始算起）显示在控制台中，因此称为“近乎实时”。

要充分利用近乎实时的数据处理功能，请确保您的应用使用的是实时兼容的 SDK 版本。

如何获得我的应用的近乎实时的性能数据？

要充分利用近乎实时的数据处理功能，您只需要确保您的应用使用与实时数据处理兼容的 Performance Monitoring SDK 版本。

以下是实时兼容的 SDK 版本：

iOS - v7.3.0 或更高版本
tvOS - v8.9.0 或更高版本
Android - v19.0.10 或更高版本（或 Firebase Android BoM v26.1.0 或更高版本）
Web — v7.14.0 或更高版本

请注意，我们始终建议使用最新版 SDK，但上文列出的任何版本都支持 Performance Monitoring 以近乎实时的方式处理您的数据。

哪些 Performance Monitoring SDK 版本兼容实时数据？

以下是与实时数据数据处理功能兼容的 SDK 版本：

iOS - v7.3.0 或更高版本
tvOS - v8.9.0 或更高版本
Android - v19.0.10 或更高版本（或 Firebase Android BoM v26.1.0 或更高版本）
Web — v7.14.0 或更高版本