Argumente für die Instrumentierung von Makro-Benchmarks

Konfigurieren Sie das Verhalten der Bibliothek mit den folgenden Instrumentierungsargumenten. Sie können sie entweder Ihrer Gradle-Konfiguration hinzufügen oder direkt anwenden, wenn Sie die Instrumentierung über die Befehlszeile ausführen. Wenn Sie diese Argumente für alle Android Studio- und Befehlszeilen-Tests festlegen möchten, fügen Sie sie testInstrumentationRunnerArguments hinzu:

android {
    defaultConfig {
        // ...
        testInstrumentationRunnerArguments["androidx.benchmark.dryRunMode.enable"] = "true"
    }
}

Sie können auch Instrumentierungsargumente einrichten, wenn Sie die Benchmarks über Android Studio ausführen. So ändern Sie die Argumente:

Wenn Sie den Makrobenchmark über die Befehlszeile ausführen, verwenden Sie -P android.testInstrumentationRunnerArguments.[name of the argument]:

./gradlew :benchmark:connectedAndroidTest -P android.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=BaselineProfile

Wenn Sie den Befehl am instrument direkt aufrufen (was in CI-Testumgebungen der Fall sein kann), übergeben Sie das Argument mit -e an am instrument:

adb shell am instrument -e androidx.benchmark.enabledRules BaselineProfile -w com.example.macrobenchmark/androidx.test.runner.AndroidJUnitRunner

Weitere Informationen zum Konfigurieren von Benchmarks in CI finden Sie unter Benchmarking in CI.

androidx.benchmark.compilation.enabled

Hiermit können Sie die Kompilierung zwischen den einzelnen Iterationen des Benchmarks deaktivieren. Standardmäßig wird die Zielanwendung zwischen den einzelnen Benchmarks neu installiert und neu kompiliert, um CompilationMode zu berücksichtigen, das an measureRepeated übergeben wird. Wenn Sie diese Option deaktivieren, können Sie sowohl die Neuinstallation als auch die Kompilierung überspringen, wenn Sie beispielsweise die Ziel-App einmal vollständig kompilieren möchten, bevor Sie die Testsuite ausführen und alle Benchmarks mit diesem vollständig kompilierten Ziel ausführen.

• Argumenttyp:boolescher Wert
• Standardeinstellung:true

androidx.benchmark.dryRunMode.enable

Damit können Sie Benchmarks in einer einzigen Schleife ausführen, um zu prüfen, ob sie ordnungsgemäß funktionieren. Sie können sie im Rahmen der Überprüfung mit regulären Tests verwenden.

• Argumenttyp:boolescher Wert
• Standardeinstellung:false

androidx.benchmark.enabledRules

Ermöglicht es, Ausführungen auf nur einen Testtyp zu filtern: Generierung eines Baseline-Profils oder Macrobenchmark-Test. Durch Kommas getrennte Listen werden ebenfalls unterstützt.

• Argumenttyp: String
• Verfügbare Optionen:
  • Macrobenchmark
  • BaselineProfile
• Standardwert:Nicht angegeben

androidx.benchmark.junit4.SideEffectRunListener

Es kann zu inkonsistenten Benchmarkergebnissen kommen, wenn während des Benchmarks andere Hintergrundarbeiten ausgeführt werden.

Wenn Sie Hintergrundarbeiten während des Benchmarkings deaktivieren möchten, legen Sie den listener-Typ des Instrumentierungsarguments auf androidx.benchmark.junit4.SideEffectRunListener fest.

• Argumenttyp:String
• Verfügbare Optionen:
  • androidx.benchmark.junit4.SideEffectRunListener
• Standardwert:nicht angegeben

androidx.benchmark.fullTracing.enable

Aktiviert androidx.tracing.perfetto-Tracepoints wie das Compose-Tracing von Jetpack Compose.

Sie müssen Ihr Projekt so einrichten, dass Sie Zusammensetzungs-Tracings aus Benchmarks erfassen können. Weitere Informationen finden Sie unter Einen Trace mit Jetpack Macrobenchmark erfassen.

• Argumenttyp: boolescher Wert
• Standardeinstellung: false

androidx.benchmark.profiling.mode

Ermöglicht das Erfassen von Ablaufdateien während der Ausführung der Benchmarks. Die verfügbaren Optionen entsprechen denen der Microbenchmark-Bibliothek. Weitere Informationen finden Sie in den Beschreibungen unter Microbenchmark profilieren.

• Argumenttyp:String
• Verfügbare Optionen:
  • MethodTracing
  • StackSampling
  • None
• Standardeinstellung:None

androidx.benchmark.startupProfiles.enable

Hiermit können Sie die Generierung von Startprofilen während des Benchmarkings deaktivieren.

• Argumenttyp: boolescher Wert
• Standardeinstellung:true

androidx.benchmark.suppressErrors

Akzeptiert eine durch Kommas getrennte Liste von Fehlern, die in Warnungen umgewandelt werden sollen.

• Argumenttyp: Liste von Strings

• Verfügbare Optionen:

  • DEBUGGABLE

    Der Fehler DEBUGGABLE gibt an, dass das Zielpaket mit debuggable=true im Manifest ausgeführt wird, was die Laufzeitleistung drastisch reduziert, um Debug-Funktionen zu unterstützen. Um diesen Fehler zu vermeiden, führen Sie Benchmarks mit debuggable=false aus. Das Argument „debuggable“ wirkt sich auf die Ausführungsgeschwindigkeit aus, sodass sich Benchmarkverbesserungen möglicherweise nicht auf die Leistung bei echten Nutzern auswirken oder die Release-Leistung beeinträchtigen.

  • LOW-BATTERY

    Wenn der Akkustand niedrig ist, reduzieren Geräte häufig die Leistung, um den verbleibenden Akku zu schonen, z. B. durch Deaktivieren der großen Kerne. Das passiert auch, wenn die Geräte angeschlossen sind. Unterdrücken Sie diesen Fehler nur, wenn Sie die App bewusst mit reduzierter Leistung profilieren.

  • EMULATOR

    Der Fehler EMULATOR gibt an, dass der Benchmark auf einem Emulator ausgeführt wird, der nicht repräsentativ für die Geräte echter Nutzer ist. Verbesserungen bei Emulator-Benchmarks können sich nicht auf die Leistung echter Nutzer auswirken oder die Leistung des Geräts beeinträchtigen. Verwenden Sie stattdessen ein physisches Gerät für den Benchmark. Unterdrücken Sie diesen Fehler nur mit äußerster Vorsicht.

  • NOT-PROFILEABLE

    Das Zielpaket $packageName wird ohne <profileable shell=true> ausgeführt. Unter Android 10 und 11 ist die Option „Profileable“ erforderlich, damit Macrobenchmark detaillierte Informationen zum Trace aus dem Zielprozess erfassen kann, z. B. System-Tracing-Abschnitte, die in der App oder in Bibliotheken definiert sind. Unterdrücken Sie diesen Fehler nur mit äußerster Vorsicht.

  • METHOD-TRACING-ENABLED

    Für den Macrobenchmark, der für die App ausgeführt wird, ist die Methode „Method Tracing“ aktiviert. Dadurch läuft die VM langsamer als üblich. Berücksichtigen Sie die Messwerte aus den Ablaufdateien daher nur relativ. Vergleichen Sie beispielsweise, wie schnell der erste Durchlauf im Vergleich zum zweiten ist. Wenn Sie diesen Fehler unterdrücken, kann dies zu ungenauen Ergebnissen führen, wenn Sie Benchmarks für Builds mit unterschiedlichen Methoden-Tracing-Optionen vergleichen.

• Standardeinstellung: leere Liste

additionalTestOutputDir

Hier wird konfiguriert, wo JSON-Benchmarkberichte und ‑Profilierungsergebnisse auf dem Gerät gespeichert werden.

• Argumenttyp:Pfadstring
• Standardeinstellung:externes Verzeichnis des Test-APK