撰寫 Macrobenchmark

Stay organized with collections Save and categorize content based on your preferences.

使用 Macrobenchmark 程式庫測試應用程式的大型用途,包括應用程式啟動及複雜的 UI 操控方式,例如捲動 RecyclerView 或執行動畫。如要測試程式碼較小的區域,請參閱 microbenchmark 程式庫

程式庫會將效能評定結果輸出至 Android Studio 主控台和 JSON 檔案,其中包含更多詳細資料。這個套件也提供您可以在 Android Studio 中載入及分析的追蹤檔。

在持續整合 (CI) 環境中使用 Macrobenchmark 程式庫。詳情請參閱持續整合的基準

您可使用 Macrobenchmark 產生基準設定檔。請按照以下指南設定 Marcobenchmark 程式庫,然後建立基準設定檔

專案設定

建議您將 Macrobenchmark 與最新版的 Android Studio 搭配使用,因為該 IDE 版本中的新功能已與 Macrobenchmark 整合。

設定 Macrobenchmark 模組

Macrobenchmark 需要獨立於應用程式程式碼之外的 com.android.test 模組,負責執行評估應用程式的測試。

您可以在 Android Studio 中使用範本來簡化 Macrobenchmark 模組設定。效能評定模組範本會在專案中自動建立模組,以評估由應用程式模組建立的應用程式,包括新創公司效能評定範例。

如要使用模組範本建立新模組,請執行下列步驟:

  1. 在 Android Studio 的「Project」面板中,於專案或模組上按一下滑鼠右鍵,然後依序點選「New」>「Module」

  2. 從「Templates」 窗格中選取「Benchmark」

  3. 您可以自訂目標應用程式 (要效能評定的應用程式) 以及新的 Macrobenchmark 模組的套件和模組名稱。

  4. 按一下「Finish」

效能評定模組範本

設定應用程式

如要對應用程式進行參照 (稱為巨集效能評定的目標),應用程式必須為 profileable,以便在不影響效能的情況下讀取詳細的追蹤記錄資訊。模組精靈會將 <profileable> 標記自動新增至應用程式的 AndroidManifest.xml 檔案。

盡可能將效能評定應用程式設定為接近發布版本 (或正式版)。請將其設為無法進行偵錯,最好是開啟壓縮功能,藉此提升效能。通常,您只要建立發布版本的變化版本,就能以相同方式執行發布作業,不過系統會透過偵錯金鑰在本機簽署。您也可以使用 initWith 指示 Gradle 進行以下操作:

Groovy

buildTypes {
    release {
        minifyEnabled true
        shrinkResources true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }

    benchmark {
        initWith buildTypes.release
        signingConfig signingConfigs.debug
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'benchmark-rules.pro'
    }
}

Kotlin

buildTypes {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
    }

    create("benchmark") {
        initWith(getByName("release"))
        signingConfig = signingConfigs.getByName("debug")
    }
}

執行 Gradle 同步處理、開啟左側的「Build Variants」面板,然後選取應用程式和 Macrobenchmark 模組的效能評定變化版本。確保執行效能評定會建構及測試應用程式的正確版本:

選取效能評定變化版本

(選用) 設定多模組應用程式

如果您的應用程式有多個 Gradle 模組,您必須確保建構指令碼知道要編譯哪個建構變化版本。在未設定的情況下,新增的 benchmark 建構作業類型會導致建構失敗,並顯示下列錯誤訊息:

> Could not resolve project :shared.
     Required by:
         project :app
      > No matching variant of project :shared was found.
      ...

如要解決這個問題,請將 matchingFallbacks 屬性加入 :macrobenchmark:app 模組的 benchmark buildType 中。您的其他 Gradle 模組可以具備和之前相同的設定。

Groovy

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
}

Kotlin

create("benchmark") {
    initWith(getByName("release"))
    signingConfig = signingConfigs.getByName("debug")

    matchingFallbacks += listOf('release')
}

在專案中選取建構變化版本時,請為 :app:macrobenchmark 模組選擇 benchmark,如為應用程式中的任何其他模組,請選擇 release,如下方所示下圖:

多模組專案的效能評定變化版本,已選取版本和效能評定建構作業類型

詳情請參閱變體感知依附元件管理

(選用) 設定變種版本

如果應用程式中設定了多個變種版本,您必須設定 :macrobenchmark 模組,以便系統知道要建構和基準的應用程式的變種版本。如果沒有進行這項設定,您可能會收到類似使用多個 Gradle 模組的建構錯誤:

Could not determine the dependencies of task ':macrobenchmark:connectedBenchmarkAndroidTest'.
> Could not determine the dependencies of null.
   > Could not resolve all task dependencies for configuration ':macrobenchmark:benchmarkTestedApks'.
      > Could not resolve project :app.
        Required by:
            project :macrobenchmark
         > The consumer was configured to find a runtime of a component, as well as attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'benchmark', attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '7.3.0'. However we cannot choose between the following variants of project :app:
             - demoBenchmarkRuntimeElements
             - productionBenchmarkRuntimeElements
           All of them match the consumer attributes:
           ...

在本指南中,在 :app 模組中使用兩個變種版本 -- demoproduction,如以下程式碼片段所示:

Groovy

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
        // ...
    }

    production {
        dimension 'environment'
        // ...
    }
}

Kotlin

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
        // ...
    }
    create("production") {
        dimension = "environment"
        // ...
    }
}

有兩種方法可以設定多個變種版本基準:

使用 missingDimensionStrategy

:macrobenchmark 模組的 defaultConfig 中指定 missingDimensionStrategy,會指示建構系統改回使用版本維度。如果在模組中未找到這些維度,您必須指定要使用的維度。在以下範例中,系統會使用 production 變種版本做為預設維度:

Groovy

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Kotlin

defaultConfig {
    missingDimensionStrategy("environment", "production")
}

這樣一來,:macrobenchmark 模組只能建構指定的變種版本並用效能評定,如果您知道只有一個變種版本具有要進行效能評定的適當設定,這就非常實用。

:macrobenchmark 模組中定義變種版本

如要建構其他變種版本並進行效能評定,您必須在 :macrobenchmark 模組中定義變種版本。指定方式與 :app 模組中相似,但僅需將 productFlavors 指派給 dimension,無需進行其他設定:

Groovy

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
    }

    production {
        dimension 'environment'
    }
}

Kotlin

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
    }
    create("production") {
        dimension = "environment"
    }
}

定義並同步處理專案後,從「Build Variants」窗格中選擇所需的建構變數:

專案的效能評定變化版本,已選取顯示 productionBenchmark 的變種版本和版本

詳情請參閱解決與變數比對相關的建構錯誤一文。

建立 Macrobenchmark 類別

效能評定測試是透過 Macrobenchmark 程式庫中的 MacrobenchmarkRule JUnit4 規則 API 提供。其中包含 measureRepeated 方法,讓您指定關於如何執行目標應用程式並進行效能評定的各種條件。

您必須指定目標應用程式的 packageName、要評估的 metrics,以及要執行效能評定的 iterations

Kotlin

@LargeTest
@RunWith(AndroidJUnit4::class)
class SampleStartupBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = TARGET_PACKAGE,
        metrics = listOf(StartupTimingMetric()),
        iterations = 5,
        setupBlock = {
            // Press home button before each run to ensure the starting activity isn't visible.
            pressHome()
        }
    ) {
        // starts default launch activity
        startActivityAndWait()
    }
}

Java

@LargeTest
@RunWith(AndroidJUnit4.class)
public class SampleStartupBenchmark {
    @Rule
    public MacrobenchmarkRule benchmarkRule = new MacrobenchmarkRule();

    @Test
    public void startup() {
        benchmarkRule.measureRepeated(
            /* packageName */ TARGET_PACKAGE,
            /* metrics */ Arrays.asList(new StartupTimingMetric()),
            /* iterations */ 5,
            /* measureBlock */ scope -> {
                // starts default launch activity
                scope.startActivityAndWait();
                return Unit.INSTANCE;
            }
        );
    }
}

如需自訂效能評定的所有選項,請參閱自訂效能評定一節。

執行效能評定測試

在 Android Studio 中執行測試,以測量應用程式在裝置上的效能。效能評定的測試方式,與使用其他類別或測試方法執行其他 @Test 的方式相同,如下所示:

在測試類別旁執行虛線動作的 Macrobenchmark

您也可以透過執行 ConnectedCheck 指令,在指令列執行 Gradle 模組中的所有效能評定:

./gradlew :macrobenchmark:connectedCheck

或執行單一測試:

./gradlew :macrobenchmark:connectedCheck -P android.testInstrumentationRunnerArguments.class=com.example.macrobenchmark.startup.SampleStartupBenchmark#startup

如要瞭解如何在持續整合服務中執行及監控效能評定,請參閱「CI 效能評定」一節。

效能評定結果

效能評定執行完畢後,指標會直接顯示在 Android Studio 中,也會在 JSON 檔案中列為 CI 使用情形的輸出內容。每項經過評估的疊代作業都會擷取個別系統追蹤記錄。如要開啟結果追蹤記錄,請按一下「Test Results」窗格中的任一連結,如下圖所示。

Macrobenchmark 啟動結果

載入追蹤記錄時,Android Studio 會提示您選取要分析的程序。應用程式會預先填入目標應用程式程序:

選取工作室追蹤程序

追蹤檔載入完成後,Studio 會在 CPU 分析器工具中顯示結果:

Studio 追蹤記錄

JSON 報表和所有剖析追蹤記錄也會自動從裝置複製到主機。寫入主體機器的位置如下:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/

手動存取追蹤檔

如果您想使用 Perfetto 工具分析追蹤檔,還需要執行其他步驟。Perfetto 可讓您查看在追蹤記錄期間裝置上透過裝置處理的所有程序,而 Android Studio 的 CPU 分析器會將檢查限制為單一程序。

如果您從 Android Studio 叫用測試或使用 Gradle 指令列,追蹤檔會自動從裝置複製到主機。這些程式碼會在主機機器上寫入:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/TrivialStartupBenchmark_startup[mode=COLD]_iter002.perfetto-trace

在主機系統上取得追蹤檔後,在選單中依序點選「File」>「Open」,即可透過 Android Studio 開啟追蹤檔。如上節所示的分析器工具檢視畫面。

設定錯誤

如果應用程式設定錯誤 (可偵錯或無法剖析),Macrobenchmark 會傳回錯誤,而不是回報不正確或不完整的測量結果。您可以使用 androidx.benchmark.suppressErrors 引數略過這些錯誤。

此外,系統在評估模擬器或低電量裝置時也會回報錯誤,因為這樣可能會影響核心可用性和時鐘速度。

自訂效能評定

measureRepeated 函式可接受各種參數,而這些參數會影響程式庫收集的指標、應用程式的啟動與編譯方式,或是效能評定測試將執行的疊代次數。

擷取指標

指標是指擷取效能評定資訊的主要類型資訊。可用選項包括 StartupTimingMetricFrameTimingMetricTraceSectionMetric。如要進一步瞭解相關資訊,請參閱擷取指標頁面。

使用自訂事件改善追蹤記錄資料

您可以透過自訂追蹤記錄事件,對應用程式進行檢測;透過其他追蹤記錄報表查看,有助您找出應用程式特有的問題。如要進一步瞭解如何建立自訂追蹤事件,請參閱定義自訂事件指南。

CompilationMode

巨集效能評定可指定 CompilationMode,這會定義應在 DEX 位元組代碼 (APK 中的位元組碼格式) 預先編譯至機器程式碼 (類似 pre-complied 的應用程式數量-編譯完成的 C++)。

根據預設,巨集效能評定是透過 CompilationMode.DEFAULT 執行,後者會在 Android 7 (API 層級 24) 以上版本中安裝效能評定設定檔 (如果有的話)。如果您使用的是 Android 6 (API 層級 23) 以下的版本,編譯模式會將所有 APK 編譯為預設系統行為。

如果目標應用程式包含效能評定設定檔和 ProfileInstaller 程式庫,您就可以安裝效能評定設定檔。

在 Android 7 以上版本中,您可以自訂 CompilationMode 來影響裝置端預先編譯的資料量,會模擬不同時間的先進 (AOT) 編譯或 JIT 快取功能。請參閱 CompilationMode.FullCompilationMode.PartialCompilationMode.None

這項功能以 ART 編譯指令為基礎。每個效能評定會在清除資料前清除設定檔資料,以確保效能評定之間的非干擾情況。

啟動模式

如要執行活動開始,您可以傳遞預先定義的啟動模式 (COLDWARMHOT 其中之一)。這個參數會改變活動啟動時的方式,以及測試開始的流程狀態。

如要進一步瞭解新創公司的類型,請參閱 Android Vitals 啟動說明文件

範例

範例專案是 GitHub 上的 android/performance-samples 存放區的一部分。

提供意見

如要回報或提交 Jetpack Macrobenchmark 的功能要求,請參閱公開問題追蹤工具