Firebase Performance Monitoring 使用入门 (Android)

准备工作

将 Firebase 添加到您的 Android 项目（如果尚未添加）。

第 1 步：将 Performance Monitoring SDK 添加到您的应用

添加 Performance Monitoring SDK 后，Firebase 会自动开始收集应用的界面渲染数据以及与应用生命周期相关的数据（例如应用启动时间）。如需让 Firebase 能够监控网络请求，您还必须添加 Performance Monitoring Gradle 插件（下一步）。

1. 在模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，添加 Performance Monitoring 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.15.0"))
   
       // Add the dependency for the Performance Monitoring library
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-perf")
   }

   借助 Firebase Android BoM，可确保您的应用使用的始终是 Firebase Android 库的兼容版本。

   （替代方法） 在不使用 BoM 的情况下添加 Firebase 库依赖项

   如果您选择不使用 Firebase BoM，则必须在每个 Firebase 库的依赖项行中指定相应的库版本。

   请注意，如果您在应用中使用多个 Firebase 库，我们强烈建议您使用 BoM 来管理库版本，从而确保所有版本都兼容。

   dependencies {
       // Add the dependency for the Performance Monitoring library
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-perf:21.0.5")
   }

   是否想要查找 Kotlin 专用的库模块？ 从 2023 年 10 月 (Firebase BoM 32.5.0) 开始，Kotlin 和 Java 开发者可以依赖于主库模块（如需了解详情，请参阅关于此计划的常见问题解答）。

2. 重新编译您的应用。

第 2 步：将 Performance Monitoring Gradle 插件添加到您的应用

添加 Performance Monitoring Gradle 插件后，Firebase 会自动开始收集 HTTP/HTTPS 网络请求的数据。借助该插件，您还可以使用 @AddTrace 注解对自定义代码跟踪进行插桩 (instrument)。

Performance Monitoring 插件的工作方式

在您的代码转换为 DEX 文件之前，Performance Monitoring 插件会使用 Transform API 和 ASM 字节码插桩框架来访问应用的已编译类文件并向代码插桩（以便衡量性能）。向代码插桩所需的时间主要取决于类的数量和大小。

如果应用编译所需时间超出您的预期，请考虑以下选项：

• 在编译时为您的调试 build 停用 Performance Monitoring 插件
• 模块化代码以优化构建速度

1. 在您的根级（项目级）Gradle 文件（<project>/build.gradle.kts 或 <project>/build.gradle）中，添加 Performance Monitoring Gradle 插件：

   Kotlin

   plugins {
       // To benefit from the latest Performance Monitoring plugin features,
       // update your Android Gradle plugin dependency to at least v3.4.0
       id("com.android.application") version "7.3.0" apply false
   
       // Make sure that you have the Google services Gradle plugin dependency
       id("com.google.gms.google-services") version "4.4.2" apply false
   
       // Add the dependency for the Performance Monitoring Gradle plugin
       id("com.google.firebase.firebase-perf") version "1.4.2" apply false
   }

   Groovy

   plugins {
       // To benefit from the latest Performance Monitoring plugin features,
       // update your Android Gradle plugin dependency to at least v3.4.0
       id 'com.android.application' version '7.3.0' apply false
   
       // Make sure that you have the Google services Gradle plugin dependency
       id 'com.google.gms.google-services' version '4.4.2' apply false
   
       // Add the dependency for the Performance Monitoring Gradle plugin
       id 'com.google.firebase.firebase-perf' version '1.4.2' apply false
   }

2. 在您的模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，添加 Performance Monitoring Gradle 插件：

   Kotlin

   plugins {
       id("com.android.application")
   
       // Make sure that you have the Google services Gradle plugin
       id("com.google.gms.google-services")
   
       // Add the Performance Monitoring Gradle plugin
       id("com.google.firebase.firebase-perf")
       ...
   }

   Groovy

   plugins {
       id 'com.android.application'
   
       // Make sure that you have the Google services Gradle plugin
       id 'com.google.gms.google-services'
   
       // Add the Performance Monitoring Gradle plugin
       id 'com.google.firebase.firebase-perf'
       ...
   }

3. 重新编译您的应用。

第 3 步：生成性能事件以显示初始数据

当您成功将 SDK 添加到应用后，Firebase 即会开始处理事件。如果您仍在本地进行开发，请与您的应用交互以生成事件，从而触发初始数据收集和处理。

1. 生成事件的方法包括：将应用在后台和前台之间切换数次、与应用进行交互（浏览多个屏幕），以及触发网络请求。

2. 前往 Firebase 控制台的“性能”信息中心。您应该会在几分钟内看到初始数据。

   如果您没有看到初始数据，请查看问题排查提示。

第 4 步：（可选）检查日志消息中是否有性能事件

1. 您可以在构建时为 Performance Monitoring 启用调试日志记录功能，方法是在应用的 AndroidManifest.xml 文件中添加 <meta-data> 元素，如下所示：

   <application>
       <meta-data
         android:name="firebase_performance_logcat_enabled"
         android:value="true" />
   </application>

2. 检查您的日志消息中是否有错误消息。

3. Performance Monitoring 会使用 FirebasePerformance 标记其日志消息。借助 logcat 过滤功能，您可以运行以下命令来专门查看时长跟踪记录和 HTTP/HTTPS 网络请求日志记录：

   adb logcat -s FirebasePerformance

4. 检查以下类型的日志，这些日志表明 Performance Monitoring 正在记录性能事件：

   • Logging trace metric: TRACE_NAME, FIREBASE_PERFORMANCE_CONSOLE_URL
   • Logging network request trace: URL

5. 点击网址即可在 Firebase 控制台中查看您的数据。系统可能需要一些时间才能在信息中心内更新数据。

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

第 5 步：（可选）为特定代码添加自定义监控功能

如需监控与应用中特定代码相关联的性能数据，您可以对代码进行插桩处理，从而添加自定义代码跟踪记录。

借助自定义代码跟踪记录，您可以衡量应用完成一项或一组任务（例如加载一组图像或查询数据库）所需的时间。自定义代码跟踪记录的默认指标是其时长，但您也可以添加自定义指标，例如缓存命中数和内存警告。

在代码中，您可以使用 Performance Monitoring SDK 提供的 API 指定自定义跟踪记录的开始和结束（以及添加任何所需的自定义指标）。 对于 Android 应用，您还可以使用 @AddTrace 注解来监控特定方法的时长。

请访问为特定代码添加监控功能，详细了解这些功能以及如何将其添加到您的应用中。

第 6 步：部署应用，然后查看结果

使用一个或多个测试设备验证 Performance Monitoring 后，您可以将更新后的应用版本部署给用户。

您可以在 Firebase 控制台的“性能”信息中心监控性能数据。

已知问题

• Performance Monitoring Gradle 插件 v1.1.0 可能导致 Guava 依赖项不匹配，造成以下错误：

  Error:Execution failed for task ':app:packageInstantRunResourcesDebug'.
  > com.google.common.util.concurrent.MoreExecutors.directExecutor()Ljava/util/concurrent/Executor;

  如果出现此错误，您可以采取以下任一措施：

  • 将 Performance Monitoring 插件升级到 v1.1.1 或更高版本（最新版本为 v1.4.2）。

  • 替换根级（项目级）Gradle 文件（<project>/build.gradle.kts 或 <project>/build.gradle）中的 Performance Monitoring 插件依赖项行，如下所示：

    Kotlin

    buildscript {
      // ...
    
      dependencies {
        // ...
    
        // Replace the standard Performance Monitoring plugin dependency line, as follows:
        classpath("com.google.firebase:perf-plugin:1.1.0") {
            exclude(group = "com.google.guava", module = "guava-jdk5")
        }
      }
    }

    Groovy

    buildscript {
      // ...
    
      dependencies {
        // ...
    
        // Replace the standard Performance Monitoring plugin dependency line, as follows:
        classpath('com.google.firebase:perf-plugin:1.1.0') {
            exclude group: 'com.google.guava', module: 'guava-jdk5'
        }
      }
    }

• Performance Monitoring 会根据 HTTP 内容长度标头中设置的值，报告 HTTP 网络请求的总载荷大小。此值有时可能并不准确。

• 在多进程 Android 应用中，Performance Monitoring 仅支持其中的主进程。

后续步骤

• 查看并运行 GitHub 上的 Performance Monitoring Android 代码示例。

• 详细了解 Performance Monitoring 自动收集的数据：

  • 与应用生命周期相关的数据，例如应用启动时间
  • 应用中的界面渲染数据
  • 应用发出的 HTTP/HTTPS 网络请求的数据

• 在 Firebase 控制台中查看、跟踪和过滤性能数据。

• 通过对自定义代码跟踪记录进行插桩处理，针对应用的特定任务或工作流添加监控功能。

• 使用属性来过滤性能数据。