MacroBenchmark schreiben

Verwenden Sie die Macrobenchmark-Bibliothek, um größere Anwendungsfälle Ihrer App zu testen, einschließlich des App-Starts und komplexer UI-Manipulationen wie das Scrollen eines RecyclerView oder das Ausführen von Animationen. Wenn Sie kleinere Bereiche Ihres Codes testen möchten, lesen Sie den Artikel zu Microbenchmark-Bibliothek. Auf dieser Seite wird beschrieben, wie Sie die Macrobenchmark-Bibliothek einrichten.

Die Bibliothek gibt Benchmark-Ergebnisse sowohl in der Android Studio-Konsole als auch in einer JSON-Datei mit weiteren Details aus. Außerdem werden Trace-Dateien bereitgestellt, die Sie in Android Studio laden und analysieren können.

Verwenden Sie die Macrobenchmark-Bibliothek in einer Continuous Integration-Umgebung (CI), wie es unter Benchmarking in Continuous Integration beschrieben ist.

Mit Macrobenchmark können Sie Baseline-Profile erstellen. Richten Sie zuerst die Macrobenchmark-Bibliothek ein und erstellen Sie dann ein Baseline Profil.

Projekt einrichten

Wir empfehlen, Macrobenchmark mit der neuesten Version von Android Studio zu verwenden, um die Funktionen der IDE zu nutzen, die in Macrobenchmark integriert sind.

Macrobenchmark-Modul einrichten

Für Macrobenchmarks ist ein com.android.test -Modul erforderlich, das vom App-Code getrennt ist und für die Ausführung der Tests verantwortlich ist, mit denen Ihre App gemessen wird.

In Android Studio ist eine Vorlage verfügbar, um die Einrichtung des Macrobenchmark-Moduls zu vereinfachen. Mit der Vorlage für das Benchmark-Modul wird automatisch ein Modul in Ihrem Projekt erstellt, mit dem die von einem App-Modul erstellte App gemessen werden kann, einschließlich eines Beispiels für einen Benchmark für den Start.

So erstellen Sie mit der Modulvorlage ein neues Modul:

1. Klicken Sie in Android Studio im Bereich Project (Projekt) mit der rechten Maustaste auf Ihr Projekt oder Modul und wählen Sie New > Module (Neu > Modul) aus.

2. Wählen Sie im Bereich Templates die Option Benchmark aus. Sie können die Ziel-App (die App, für die ein Benchmark durchgeführt werden soll) sowie den Paket- und Modul namen für das neue Macrobenchmark-Modul anpassen.

3. Klicken Sie auf Finish (Fertig).

Abbildung 1 : Vorlage für das Benchmark-Modul.

App einrichten

Um einen Benchmark für eine App durchzuführen, die als das Ziel des Macrobenchmarks bezeichnet wird, muss die App profileable sein. Dadurch können detaillierte Trace-Informationen gelesen werden, ohne die Leistung zu beeinträchtigen. Der Modulassistent fügt das <profileable> Tag automatisch der Datei AndroidManifest.xml der App hinzu.

Die Ziel-App muss ProfilerInstaller 1.3 oder höher enthalten. Die Macrobenchmark-Bibliothek benötigt diese Version, um die Profilerfassung und das Zurücksetzen sowie das Löschen des Shader-Caches zu ermöglichen.

Konfigurieren Sie die App, für die ein Benchmark durchgeführt wird, so nah wie möglich an der Release- oder Produktionsversion. Legen Sie sie als nicht debugfähig fest und aktivieren Sie nach Möglichkeit die Minimierung, um die Leistung zu verbessern. Normalerweise erstellen Sie dazu eine Kopie der Release Variante, die dieselbe Funktion hat, aber lokal mit Debug-Schlüsseln signiert ist. Alternativ können Sie mit initWith Gradle anweisen, dies für Sie zu tun:

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

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

buildTypes {
    release {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "keep-rules.pro"
        )
        // In real app, this would use its own release keystore
        signingConfig = signingConfigs.getByName("debug")
        baselineProfile.automaticGenerationDuringBuild = true
    }
}
build.gradle.kts

Damit beim Ausführen des Benchmarks sowohl die richtige Variante Ihrer App erstellt als auch getestet wird, wie in Abbildung 2 dargestellt, gehen Sie so vor:

1. Führen Sie eine Gradle-Synchronisierung durch.
2. Öffnen Sie den Build Variants Bereich.
3. Wählen Sie die Benchmark-Variante sowohl der App als auch des Macrobenchmark-Moduls aus.

Abbildung 2 Benchmark-Variante auswählen.

(Optional) App mit mehreren Modulen einrichten

Wenn Ihre App mehrere Gradle-Module hat, müssen Sie in Ihren Build-Skripts angeben, welche Build-Variante kompiliert werden soll. Fügen Sie die Property matchingFallbacks dem benchmark Build-Typ Ihrer :macrobenchmark und :app Module hinzu. Die übrigen Gradle-Module können dieselbe Konfiguration wie zuvor haben.

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

    matchingFallbacks += listOf("release")
 }

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
 }

Andernfalls führt der neu hinzugefügte Build-Typ benchmark dazu, dass der Build fehlschlägt und die folgende Fehlermeldung angezeigt wird:

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

Wenn Sie die Build-Varianten in Ihrem Projekt auswählen, wählen Sie benchmark für :app und :macrobenchmark Module und release für alle anderen Module in Ihrer App aus, wie in Abbildung 3 dargestellt:

Abbildung 3 Benchmark-Varianten für ein Projekt mit mehreren Modulen, bei dem die Build-Typen „release“ und „benchmark“ ausgewählt sind.

Weitere Informationen finden Sie unter Variantenspezifische Abhängigkeitsverwaltung verwenden.

(Optional) Produktvarianten einrichten

Wenn Sie in Ihrer App mehrere Produktvarianten festgelegt haben, konfigurieren Sie das :macrobenchmark Modul so, dass es weiß, welche Produktvariante Ihrer App erstellt und für die ein Benchmark durchgeführt werden soll.

In den Beispielen auf dieser Seite werden die beiden Produktvarianten im :app Modul: demo und production verwendet, wie im folgenden Snippet dargestellt:

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

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

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

Ohne diese Konfiguration kann ein Build-Fehler ähnlich dem bei mehreren Gradle-Modulen auftreten:

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:
           ...

In den folgenden beiden Abschnitten werden Möglichkeiten zum Konfigurieren von Benchmarks mit mehreren Produktvarianten beschrieben.

missingDimensionStrategy verwenden

Wenn Sie missingDimensionStrategy in der defaultConfig des :macrobenchmark Moduls angeben, wird das Build-System angewiesen, auf die Variantendimension zurückzugreifen. Geben Sie an, welche Dimensionen verwendet werden sollen, wenn sie im Modul nicht gefunden werden. Im folgenden Beispiel wird die Variante production als Standard dimension verwendet:

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

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Auf diese Weise kann das :macrobenchmark Modul nur die angegebene Produktvariante erstellen und für diese einen Benchmark durchführen. Das ist hilfreich, wenn Sie wissen, dass nur eine Produkt variante die richtige Konfiguration für einen Benchmark hat.

Produktvarianten im Modul „:macrobenchmark“ definieren

Wenn Sie andere Produktvarianten erstellen und für diese einen Benchmark durchführen möchten, definieren Sie sie im :macrobenchmark Modul. Geben Sie sie ähnlich wie im :app Modul an, weisen Sie productFlavors aber nur einer dimension zu. Es sind keine weiteren Einstellungen erforderlich:

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

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

    production {
        dimension 'environment'
    }
}

Nachdem Sie das Projekt definiert und synchronisiert haben, wählen Sie die entsprechende Build-Variante aus dem Build Variants Bereich (Build-Varianten) aus, wie in Abbildung 4 dargestellt:

Abbildung 4 Benchmark-Varianten für das Projekt mit Produktvarianten, bei denen „productionBenchmark“ und „release“ ausgewählt sind.

Weitere Informationen finden Sie unter Build-Fehler im Zusammenhang mit der Varianten übereinstimmung beheben.

Macrobenchmark-Klasse erstellen

Benchmark-Tests werden über die MacrobenchmarkRule-JUnit4-Regel -API in der Macrobenchmark-Bibliothek bereitgestellt. Sie enthält eine measureRepeated-Methode , mit der Sie verschiedene Bedingungen für die Ausführung und den Benchmark der Ziel -App angeben können.

Sie müssen mindestens den packageName der Ziel-App, die zu messenden metrics und die Anzahl der iterations angeben, die der Benchmark ausführen muss.

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

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = TARGET_PACKAGE,
        metrics = listOf(StartupTimingMetric()),
        iterations = DEFAULT_ITERATIONS,
    ) {
        // starts default launch activity
        uiAutomator { startApp(TARGET_PACKAGE) }
    }
}
SampleStartupBenchmark.kt

@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;
            }
        );
    }
}

Alle Optionen zum Anpassen Ihres Benchmarks finden Sie im Abschnitt Customize the benchmarks.

Benchmark ausführen

Führen Sie den Test in Android Studio aus, um die Leistung Ihrer App auf Ihrem Gerät zu messen. Sie können die Benchmarks auf dieselbe Weise ausführen wie jeden anderen @Test. Verwenden Sie dazu die Gutter-Aktion neben Ihrer Testklasse oder -methode, wie in Abbildung 5 dargestellt.

Abbildung 5 Macrobenchmark mit Gutter-Aktion neben der Test klasse ausführen.

Sie können auch alle Benchmarks in einem Gradle-Modul über die Befehlszeile ausführen, indem Sie den connectedCheck Befehl ausführen:

./gradlew :macrobenchmark:connectedCheck

Sie können einen einzelnen Test ausführen, indem Sie Folgendes ausführen:

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

Informationen zum Ausführen und Überwachen von Benchmarks in Continuous Integration finden Sie unter Benchmarking in Continuous Integration.

Benchmark-Ergebnisse

Nach einer erfolgreichen Benchmark-Ausführung werden die Messwerte direkt in Android Studio angezeigt und für die CI-Nutzung in einer JSON-Datei ausgegeben. Bei jeder gemessenen Iteration wird ein separater System-Trace erfasst. Sie können diese Trace-Ergebnisse öffnen, indem Sie im Bereich Test Results (Testergebnisse) auf die Links klicken, wie in Abbildung 6 dargestellt:

Abbildung 6 Macrobenchmark-Ergebnisse für den Start.

Wenn der Trace geladen ist, werden Sie in Android Studio aufgefordert, den zu analysierenden Prozess auszuwählen. Die Auswahl ist mit dem Prozess der Ziel-App vorab ausgefüllt, wie in Abbildung 7 dargestellt:

Abbildung 7 Auswahl des Studio-Trace-Prozesses.

Nachdem die Trace-Datei geladen wurde, werden die Ergebnisse in Studio im CPU-Profiler -Tool angezeigt:

Abbildung 8 Studio-Trace.

JSON-Berichte und alle Profiling-Traces werden außerdem automatisch vom Gerät auf den Host kopiert. Sie werden auf dem Hostcomputer an folgendem Speicherort geschrieben:

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

Manuell auf Trace-Dateien zugreifen

Wenn Sie eine Trace-Datei mit dem Perfetto Tool analysieren möchten, sind zusätzliche Schritte erforderlich. Mit Perfetto können Sie alle Prozesse untersuchen, die während des Traces auf dem Gerät ausgeführt werden, während der CPU-Profiler von Android Studio die Untersuchung auf einen einzelnen Prozess beschränkt.

Wenn Sie die Tests in Android Studio oder über die Gradle-Befehlszeile aufrufen, werden die Trace-Dateien automatisch vom Gerät auf den Host kopiert. Sie werden auf dem Hostcomputer an folgendem Speicherort geschrieben:

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

Wenn sich die Trace-Datei auf Ihrem Hostsystem befindet, können Sie sie in Android Studio über File > Open im Menü öffnen. Dadurch wird die Ansicht des Profiler-Tools angezeigt, die im vorherigen Abschnitt dargestellt ist.

Konfigurationsfehler

Wenn die App falsch konfiguriert ist (debugfähig oder nicht profilierbar), gibt Macrobenchmark einen Fehler zurück, anstatt eine falsche oder unvollständige Messung zu melden. Sie können diese Fehler mit dem androidx.benchmark.suppressErrors Argument unterdrücken.

Macrobenchmark gibt auch Fehler zurück, wenn versucht wird, einen Benchmark auf einem Emulator oder auf einem Gerät mit niedrigem Akkustand durchzuführen, da dies die Verfügbarkeit des Kerns und die Taktfrequenz beeinträchtigen kann.

Benchmarks anpassen

Die measureRepeated Funktion akzeptiert verschiedene Parameter, die beeinflussen welche Messwerte die Bibliothek erfasst, wie Ihre App gestartet und kompiliert wird oder wie viele Iterationen der Benchmark ausführt.

Messwerte erfassen

Messwerte sind die wichtigste Art von Informationen, die aus Ihren Benchmarks extrahiert werden. Die folgenden Messwerte sind verfügbar:

• StartupTimingMetric
• FrameTimingMetric
• TraceSectionMetric

Weitere Informationen zu Messwerten finden Sie unter Macrobenchmark-Messwerte erfassen.

Trace-Daten mit benutzerdefinierten Ereignissen verbessern

Es kann hilfreich sein, Ihre App mit benutzerdefinierten Trace-Ereignissen zu instrumentieren. Diese werden im Trace-Bericht angezeigt und können auf Probleme hinweisen, die speziell für Ihre App gelten. Weitere Informationen zum Erstellen benutzerdefinierter Trace-Ereignisse finden Sie unter Benutzerdefinierte Ereignisse definieren.

CompilationMode

In Macrobenchmarks kann ein CompilationMode angegeben werden, der definiert, wie viel von der App aus DEX-Bytecode (das Bytecode-Format in einer APK) in Maschinencode (ähnlich wie vorkompiliertes C++) vorkompiliert werden muss.

Standardmäßig werden Macrobenchmarks mit CompilationMode.DEFAULT ausgeführt. Dadurch wird ein Baseline-Profil (falls verfügbar) auf Android 7 (API-Level 24) und höher installiert. Wenn Sie Android 6 (API-Level 23) oder eine frühere Version verwenden, wird die APK standardmäßig vollständig kompiliert.

Sie können ein Baseline-Profil installieren, wenn die Ziel-App sowohl ein Baseline Profil als auch die ProfileInstaller Bibliothek enthält.

Unter Android 7 und höher können Sie die CompilationMode anpassen, um die Menge der Vorkompilierung auf dem Gerät zu beeinflussen und verschiedene Stufen der Ahead-of-Time (AOT)-Kompilierung oder des JIT-Caching zu simulieren. Weitere Informationen finden Sie unter CompilationMode.Full, CompilationMode.Partial, CompilationMode.None und CompilationMode.Ignore.

Diese Funktion basiert auf ART-Kompilierungsbefehlen. Bei jedem Benchmark werden vor dem Start die Profildaten gelöscht, um Störungen zwischen Benchmarks zu vermeiden.

StartupMode

Um einen Aktivitätsstart durchzuführen, können Sie einen vordefinierten Startmodus übergeben: COLD, WARM oder HOT. Dieser Parameter ändert, wie die Aktivität gestartet wird, und den Prozessstatus zu Beginn des Tests.

Weitere Informationen zu den Starttypen finden Sie unter App-Startzeit.

Produktproben

Ein Beispielprojekt ist im Macrobenchmark Beispiel des Repositorys auf GitHub verfügbar.

Feedback geben

Wenn Sie Probleme melden oder Featureanfragen für Jetpack Macrobenchmark einreichen möchten, verwenden Sie die öffentliche Problem verfolgung.