Capturer les métriques Macrobenchmark

Les métriques sont le principal type d'informations extraites de vos benchmarks. Elles sont transmises à la fonction measureRepeated en tant que List, ce qui vous permet de préciser plusieurs métriques mesurées à la fois. Le benchmark requiert au moins un type de métrique.

L'extrait de code suivant capture les métriques de temps de rendu et de section de trace personnalisée :

benchmarkRule.measureRepeated(
    packageName = TARGET_PACKAGE,
    metrics = listOf(
        FrameTimingMetric(),
        TraceSectionMetric("RV CreateView"),
        TraceSectionMetric("RV OnBindView"),
    ),
    iterations = 5,
    // ...
)

benchmarkRule.measureRepeated(
    TARGET_PACKAGE,     // packageName
    Arrays.asList(      // metrics
        new StartupTimingMetric(),
        new TraceSectionMetric("RV CreateView"),
        new TraceSectionMetric("RV OnBindView"),
    ),
    5,                  // Iterations
    // ...
);

Dans cet exemple, RV CreateView et RV OnBindView sont les identifiants de blocs traçables définis dans RecyclerView. Le code source de la méthode createViewHolder() montre comment vous pouvez définir des blocs traçables dans votre propre code.

StartupTimingMetric, TraceSectionMetric, FrameTimingMetric et PowerMetric sont décrits plus en détail dans la suite de ce document.

Les résultats du benchmark sont générés dans Android Studio, comme illustré dans la figure 1. Si plusieurs métriques sont définies, elles sont toutes combinées dans la sortie.

StartupTimingMetric

StartupTimingMetric capture les métriques de temps de démarrage de l'application avec les valeurs suivantes :

• timeToInitialDisplayMs : temps écoulé entre le moment où le système reçoit un intent de lancement et le moment où le premier frame de la destination Activity est affiché.
• timeToFullDisplayMs : temps écoulé entre le moment où le système reçoit un intent de lancement et le moment où l'application indique qu'elle est entièrement dessinée à l'aide de la méthode reportFullyDrawn(). La mesure s'arrête une fois que le premier frame a été rendu après (ou avec) l'appel reportFullyDrawn(). Cette mesure peut ne pas être disponible sur Android 10 (niveau d'API 29) ou version antérieure.

StartupTimingMetric génère les valeurs minimale, médiane et maximale des itérations de démarrage. Pour évaluer l'amélioration du démarrage, vous devez vous concentrer sur les valeurs médianes, car elles fournissent la meilleure estimation du temps de démarrage type. Pour en savoir plus sur les facteurs qui contribuent au temps de démarrage de l'application, consultez la page Temps de démarrage de l'application.

Améliorer la précision du temps de démarrage

Les deux métriques clés pour mesurer le temps de démarrage de l'application sont le temps d'affichage initial (TTID) et le temps d'affichage total (TTFD). Le TTID correspond au temps nécessaire pour afficher le premier frame de l'interface utilisateur de l'application. Le TTFD inclut également le temps d'affichage de tout contenu chargé de manière asynchrone après l'affichage du frame initial.

Le TTFD est indiqué une fois que la méthode reportFullyDrawn() de ComponentActivity est appelée. Si reportFullyDrawn() n'est jamais appelé, le TTID est indiqué à la place. Vous devrez peut-être différer l'appel de reportFullyDrawn() jusqu'à la fin du chargement asynchrone. Par exemple, si l'interface utilisateur contient une liste dynamique telle qu'une RecyclerView ou une liste différée, elle peut être renseignée par une tâche en arrière-plan qui se terminera après le premier affichage de la liste et, par conséquent, une fois que l'interface utilisateur sera marquée comme entièrement dessinée. Dans ce cas, le remplissage de la liste n'est pas inclus dans l'analyse comparative.

Pour inclure le remplissage de la liste dans votre temps de référence, obtenez FullyDrawnReporter à l'aide de getFullyDrawnReporter(), et ajoutez-y un rapporteur dans le code de votre application. Vous devrez libérer ce rapporteur une fois que la tâche en arrière-plan aura rempli la liste.

FullyDrawnReporter n'appelle pas la méthode reportFullyDrawn() tant que tous les rapporteurs ajoutés ne sont pas libérés. En ajoutant un rapporteur jusqu'à la fin du processus en arrière-plan, le délai inclut également le temps nécessaire pour remplir la liste dans les données de temps de démarrage. Cela ne modifie pas le comportement de l'application aux yeux de l'utilisateur, mais permet aux données de temps de démarrage d'inclure le temps nécessaire pour renseigner la liste.

L'exemple suivant montre comment exécuter plusieurs tâches en arrière-plan simultanément, chacune enregistrant son propre rapport :

class MainActivity : ComponentActivity() {

    sealed interface ActivityState {
        data object LOADING : ActivityState
        data object LOADED : ActivityState
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            var activityState by remember {
                mutableStateOf(ActivityState.LOADING as ActivityState)
            }
            fullyDrawnReporter.addOnReportDrawnListener {
                activityState = ActivityState.LOADED
            }
            ReportFullyDrawnTheme {
                when(activityState) {
                    is ActivityState.LOADING -> {
                        // Display the loading UI.
                    }
                    is ActivityState.LOADED -> {
                        // Display the full UI.
                    }
                }
            }
            SideEffect {
                lifecycleScope.launch(Dispatchers.IO) {
                    fullyDrawnReporter.addReporter()

                    // Perform the background operation.

                    fullyDrawnReporter.removeReporter()
                }
                lifecycleScope.launch(Dispatchers.IO) {
                    fullyDrawnReporter.addReporter()

                    // Perform the background operation.

                    fullyDrawnReporter.removeReporter()
                }
            }
        }
    }
}

public class MainActivity extends ComponentActivity {
    private FullyDrawnReporter fullyDrawnReporter;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        fullyDrawnReporter = getFullyDrawnReporter();
        fullyDrawnReporter.addOnReportDrawnListener(() -> {
            // Trigger the UI update.
            return Unit.INSTANCE;
        });

        new Thread(new Runnable() {
            @Override
            public void run() {
                fullyDrawnReporter.addReporter();

                // Do the background work.

               fullyDrawnReporter.removeReporter();
            }
        }).start();
        new Thread(new Runnable() {
            @Override
            public void run() {
                fullyDrawnReporter.addReporter();

                // Do the background work.

                fullyDrawnReporter.removeReporter();
            }
        }).start();
    }
}

reportFullyDrawn() n'est appelé que lorsque toutes les tâches sont terminées, quel que soit l'ordre.

Si votre application utilise Jetpack Compose, vous pouvez utiliser les API suivantes pour indiquer l'état entièrement dessiné :

• ReportDrawn : indique que votre composable est immédiatement prêt à interagir.
• ReportDrawnWhen : utilise un prédicat, comme list.count > 0, pour indiquer à quel moment votre composable sera prêt à interagir.
• ReportDrawnAfter : utilise une méthode de suspension qui, lorsqu'elle se termine, indique que votre composable est prêt à interagir.

FrameTimingMetric

FrameTimingMetric capture les informations de codes temporels des frames issus d'un benchmark, telles qu'un défilement ou une animation, et génère les valeurs suivantes :

• frameOverrunMs : temps de retard du frame par rapport à son échéance. Les nombres positifs indiquent un abandon du frame et un à-coup ou une saccade visible, tandis que les nombres négatifs indiquent l'avance d'un frame par rapport à son échéance. Remarque : Cette fonctionnalité n'est disponible que sur Android 12 (niveau d'API 31) ou version ultérieure.
• frameDurationCpuMs : temps nécessaire à la génération du frame sur le processeur au niveau du thread UI et du RenderThread.

Ces mesures sont collectées par étapes de 50, 90, 95 et 99 %.

Pour savoir comment identifier et améliorer les frames trop lents, consultez Affichage lent.

TraceSectionMetric

TraceSectionMetric capture le nombre de fois qu'une section de trace correspondant au sectionName fourni se produit et la durée nécessaire. Pour l'heure, elle renvoie les durées minimale, médiane et maximale en millisecondes. La section de trace est définie soit par l'appel de fonction trace(sectionName), soit par le code entre Trace.beginSection(sectionName) et Trace.endSection() ou leurs variantes asynchrones. Il sélectionne toujours la première instance d'une section de trace capturée lors d'une mesure. Par défaut, il génère uniquement les sections de trace de votre package par défaut. Pour inclure des processus en dehors de votre package, définissez targetPackageOnly = false.

Pour en savoir plus sur le traçage, consultez Présentation du traçage système et Définir des événements personnalisés.

PowerMetric

PowerMetric capture l'évolution de puissance ou d'énergie pendant la durée du test pour les catégories d'énergie fournies. Chaque catégorie sélectionnée est divisée en sous-composants mesurables, tandis que les catégories non sélectionnées sont ajoutées à la métrique "non sélectionnée".

Ces métriques mesurent la consommation à l'échelle du système, et non pour chaque application. Elles sont limitées aux appareils Pixel 6, Pixel 6 Pro et ultérieurs :

• power<category>Uw : quantité d'énergie consommée pendant la durée de votre test dans cette catégorie.
• energy<category>Uws : quantité d'énergie transférée par unité de temps pendant la durée de votre test dans cette catégorie.

Les catégories suivantes sont incluses :

• CPU
• DISPLAY
• GPU
• GPS
• MEMORY
• MACHINE_LEARNING
• NETWORK
• UNCATEGORIZED

Avec certaines catégories, comme CPU, il peut être difficile de séparer le travail effectué par d'autres processus de celui effectué par votre propre application. Réduisez les interférences en supprimant ou en limitant les applications et les comptes inutiles.