開始使用 Android 版 Performance Monitoring

事前準備

如果您尚未將 Firebase 新增至 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) 中，加入 Android 的 Performance Monitoring 程式庫依附元件。建議您使用 Firebase Android BoM 來控制程式庫版本。

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.16.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/S 網路要求的資料。外掛程式還可讓您使用 @AddTrace 註解檢測自訂程式碼追蹤記錄。

Performance Monitoring 外掛程式的運作方式

在程式碼轉換為 DEX 檔案之前，Performance Monitoring 外掛程式會使用 Transform API 和 ASM 位元碼檢測架構來造訪應用程式的編譯類別檔案，並檢測程式碼 (以便評估效能)。檢測程式碼所需的時間，很大程度上取決於類別的數量和大小。

如果應用程式編譯時間比預期長，請考慮下列選項：

• 在編譯期間為偵錯版本停用 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.3" 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.3' 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/S 網路要求記錄：

   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 外掛程式 1.1.0 版可能會導致 Guava 依附元件不相符，導致下列錯誤：

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

  如果看到這則錯誤訊息，可以採取下列做法：

  • 將 Performance Monitoring 外掛程式升級至 1.1.1 以上版本 (最新版本為 1.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 網路要求的酬載總大小。這個值不一定準確。

• Performance Monitoring 僅支援多程序 Android 應用程式中的主程序。

後續步驟

• 查看並執行 GitHub 上的 Performance Monitoring Android 程式碼範例。

• 進一步瞭解 Performance Monitoring 自動收集的資料：

  • 與應用程式生命週期相關的資料，例如應用程式啟動時間
  • 應用程式中畫面轉譯的資料
  • 應用程式發出的 HTTP/S 網路要求資料

• 在 Firebase 控制台中查看、追蹤及篩選成效資料。

• 檢測自訂程式碼追蹤記錄，為應用程式中的特定工作或工作流程新增監控功能。

• 使用屬性篩選成效資料。