Profilage basé sur des déclencheurs

Sur Android 16 (niveau d'API 36) ou version ultérieure, ProfilingManager vous permet de capturer automatiquement des profils en réponse à des déclencheurs système, tels que les erreurs Application ne répond pas (ANR), les plantages de mémoire insuffisante (OutOfMemoryError) ou les événements de démarrage de l'application. Comme vous ne pouvez pas prévoir quand un grand nombre de ces événements se produiront sur le terrain, il n'est pas pratique de démarrer un enregistrement manuellement à l'avance. Avec le profilage basé sur des déclencheurs, le système gère la capture et fournit le profil obtenu à votre application, ce qui vous permet d'effectuer les opérations suivantes :

  • Déboguer les problèmes de stabilité : diagnostiquez les erreurs ANR et les fuites de mémoire imprévisibles.
  • Optimiser les critical user journeys (CUJ) : analysez les flux tels que le démarrage de l'application (TRIGGER_TYPE_COLD_START et TRIGGER_TYPE_APP_FULLY_DRAWN).
  • Comprendre le comportement des utilisateurs : inspectez les événements tels que les sorties d'application initiées par l'utilisateur.

Pour obtenir la liste complète des déclencheurs disponibles, consultez ProfilingTrigger.

Types de déclencheurs

Les déclencheurs diffèrent par la manière dont le système capture le profil lorsque l'événement se produit.

Déclencheurs qui utilisent la trace en arrière-plan

De nombreux déclencheurs, comme une erreur ANR, sont la conséquence d'un problème antérieur. Si vous ne démarrez une trace qu'après la détection de l'ANR par le système, vous ne verrez pas l'opération de blocage qui l'a causé. Pour capturer l'activité précédant l'événement, les déclencheurs suivants enregistrent un instantané de la trace en arrière-plan active du système. Si aucune trace en arrière-plan n'est en cours d'exécution lorsque l'événement se produit, aucun profil n'est collecté :

Déclencheurs qui lancent une nouvelle capture

Les déclencheurs suivants ne dépendent pas de la trace en arrière-plan. À la place, le système démarre une nouvelle capture de profil lorsque l'événement se produit :

Déclencheurs dont le comportement de capture varie selon l'anomalie

Pour les déclencheurs d'anomalies suivants, le type de profil capturé (enregistrement d'un instantané de la trace en arrière-plan active ou démarrage d'une nouvelle capture) et le comportement de limitation du débit dépendent de l'anomalie spécifique détectée par le système :

Configurer un déclencheur

Le code suivant montre comment s'enregistrer pour le déclencheur TRIGGER_TYPE_APP_FULLY_DRAWN et définir une période d'attente.

Kotlin

@RequiresApi(Build.VERSION_CODES.BAKLAVA)
fun recordWithTrigger() {
    val profilingManager =
        applicationContext.getSystemService(ProfilingManager::class.java) ?: return

    val triggers = ArrayList<ProfilingTrigger>()

    val triggerBuilder = ProfilingTrigger.Builder(ProfilingTrigger.TRIGGER_TYPE_APP_FULLY_DRAWN)
        .setRateLimitingPeriodHours(1)

    triggers.add(triggerBuilder.build())

    val callbackExecutor: Executor = Executors.newSingleThreadExecutor()

    val resultCallback = Consumer<ProfilingResult> { profilingResult ->
        if (profilingResult.errorCode == ProfilingResult.ERROR_NONE) {
            Log.d(
                "ProfileTest",
                "Received profiling result file=" + profilingResult.resultFilePath
            )
            setupProfileUploadWorker(profilingResult.resultFilePath)
        } else {
            Log.e(
                "ProfileTest",
                "Profiling failed errorcode=" + profilingResult.errorCode + " errormsg=" + profilingResult.errorMessage
            )
        }
    }

    profilingManager.registerForAllProfilingResults(callbackExecutor, resultCallback)
    profilingManager.addProfilingTriggers(triggers)

    Choreographer.getInstance().postFrameCallback { frameTimeNanos ->
        // This will cause the TRIGGER_TYPE_APP_FULLY_DRAWN to be emitted.
        reportFullyDrawn()
    }
}

Java

public void recordWithTrigger() {
  ProfilingManager profilingManager = getApplicationContext().getSystemService(
      ProfilingManager.class);
  List<ProfilingTrigger> triggers = new ArrayList<>();
  ProfilingTrigger.Builder triggerBuilder = new ProfilingTrigger.Builder(
      ProfilingTrigger.TRIGGER_TYPE_APP_FULLY_DRAWN);
  triggerBuilder.setRateLimitingPeriodHours(1);
  triggers.add(triggerBuilder.build());

  Executor callbackExecutor = Executors.newSingleThreadExecutor();
  Consumer<ProfilingResult> resultCallback =
      new Consumer<ProfilingResult>() {
        @Override
        public void accept(ProfilingResult profilingResult) {
          if (profilingResult.getErrorCode() == ProfilingResult.ERROR_NONE) {
            Log.d(
                "ProfileTest",
                "Received profiling result file=" + profilingResult.getResultFilePath());
            setupProfileUploadWorker(profilingResult.getResultFilePath());
          } else {
            Log.e(
                "ProfileTest",
                "Profiling failed errorcode="
                    + profilingResult.getErrorCode()
                    + " errormsg="
                    + profilingResult.getErrorMessage());
          }
        }
      };
  profilingManager.registerForAllProfilingResults(callbackExecutor, resultCallback);
  profilingManager.addProfilingTriggers(triggers);

  Choreographer.getInstance().postFrameCallback((f) -> {
    // This will cause the TRIGGER_TYPE_APP_FULLY_DRAWN to be emitted.
    reportFullyDrawn();
  });
}

Le code effectue les étapes suivantes :

  1. Récupérer le gestionnaire : récupère le service ProfilingManager.
  2. Définir un déclencheur : crée un ProfilingTrigger pour TRIGGER_TYPE_APP_FULLY_DRAWN. Cet événement se produit lorsque l'application appelle reportFullyDrawn() lors d'un démarrage à froid initié par l'activité pour signaler qu'elle a terminé le démarrage et qu'elle est interactive.
  3. Définir un délai d'attente pour le déclencheur : applique un délai d'attente d'une heure à ce déclencheur spécifique à l'aide de setRateLimitingPeriodHours en plus du limiteur de débit du système. Ce délai de refroidissement empêche l'application d'enregistrer plus d'un profil de démarrage par heure.
  4. Enregistrer l'écouteur : appelle registerForAllProfilingResults pour définir le rappel qui gère le résultat. Ce rappel reçoit le chemin d'accès du profil enregistré via getResultFilePath().
  5. Ajouter des déclencheurs : enregistre la liste des déclencheurs auprès de ProfilingManager à l'aide de addProfilingTriggers.
  6. Déclencher l'événement : publie un rappel de frame Choreographer qui appelle reportFullyDrawn() une fois que le frame suivant est dessiné, ce qui émet l'événement TRIGGER_TYPE_APP_FULLY_DRAWN vers le système, déclenchant une collecte de profils en supposant qu'une trace système en arrière-plan était en cours d'exécution et que le quota de limitation du débit est disponible. Pour que ce déclencheur se produise, assurez-vous que votre application appelle reportFullyDrawn().

Cycle de vie des déclencheurs

Les déclencheurs enregistrés persistent lors des redémarrages de l'application et du système. Vous n'avez pas besoin de réenregistrer les déclencheurs à chaque démarrage de votre application ou après un redémarrage du système. Une fois que vous avez enregistré les déclencheurs à l'aide de addProfilingTriggers, le système les gère automatiquement pour votre application jusqu'à ce que vous les supprimiez ou que l'application soit désinstallée.

Quand annuler l'enregistrement des déclencheurs ?

Étant donné que les déclencheurs enregistrés sont conservés lors des redémarrages de l'application et du système, le fait d'ignorer addProfilingTriggers lors des lancements suivants n'arrête pas les déclencheurs enregistrés lors d'une session précédente. Pour arrêter de capturer des profils pour des événements spécifiques ou pour tous les événements, appelez explicitement removeProfilingTriggersByType ou clearProfilingTriggers.

Désenregistrez les déclencheurs dans les situations suivantes :

  • Cibler des cohortes ou effectuer un rollback des indicateurs distants : vous pouvez segmenter le profilage entre les cohortes à l'aide d'indicateurs de configuration à distance ou de tests A/B. Chaque fois qu'un appareil quitte la cohorte échantillonnée ou qu'un indicateur est désactivé, annulez l'enregistrement des déclencheurs.
  • Terminer une campagne de débogage : une fois que vous avez collecté suffisamment de profils pour diagnostiquer un problème ou déployer un correctif, supprimez le déclencheur. La désinscription des déclencheurs inutiles permet de préserver l'espace de stockage de l'appareil et le quota du limiteur de débit de votre application pour d'autres requêtes de profilage.

Cycle de vie des rappels

Contrairement aux requêtes de profilage direct, les profils basés sur des déclencheurs ne fournissent des résultats qu'à un écouteur global enregistré auprès de registerForAllProfilingResults. Dans votre rappel, appelez ProfilingResult.getTriggerType pour identifier le déclencheur qui a initié la capture, puis appelez ProfilingResult.getResultFilePath pour localiser le fichier de profil enregistré. Pour en savoir plus sur les noms de fichiers des profils de déclencheur, l'extraction de fichiers avec adb et l'importation des résultats en arrière-plan, consultez Récupérer et importer des profils.

Bien que les déclencheurs persistent lors du redémarrage de l'application et du système, ce n'est pas le cas de votre rappel de résultat. Enregistrez votre rappel sur un Executor en arrière-plan une fois le démarrage de l'application terminé (afin de ne pas ralentir le démarrage à froid) pour recevoir des profils dans les deux scénarios suivants :

  • Pendant l'exécution de votre application : pour les déclencheurs qui n'arrêtent pas ou ne font pas planter votre application, le système appelle votre rappel sur le Executor fourni lorsque le déclencheur se produit et que le profil est enregistré.
  • Après l'arrêt de l'application : pour les déclencheurs qui impliquent ou précèdent souvent l'arrêt de l'application (comme TRIGGER_TYPE_ANR, TRIGGER_TYPE_OOM ou TRIGGER_TYPE_KILL_RECENTS), ou si votre application s'arrête avant la fin de la capture, le système enregistre le profil en arrière-plan et met le résultat en file d'attente lors des redémarrages de l'application et du système. Le système conserve les résultats non distribués en file d'attente pendant sept jours maximum et les distribue la prochaine fois que votre application s'exécute et appelle registerForAllProfilingResults.

Fonctionnement du traçage en arrière-plan

Pour équilibrer la surcharge de profilage avec la capture d'artefacts utiles, le système n'exécute pas de traces en arrière-plan en continu. Au lieu de cela, il échantillonne périodiquement en démarrant des traces en arrière-plan à des intervalles aléatoires.

Les traces en arrière-plan déclenchées par le système utilisent un tampon circulaire dont la taille maximale est définie par le système. Lorsque le tampon est plein, les nouvelles données de trace écrasent les données les plus anciennes. Comme illustré dans la figure 1, lorsqu'un déclencheur enregistré se déclenche alors qu'une trace en arrière-plan est active et qu'un quota de limitation du débit est disponible, le système enregistre l'instantané du tampon circulaire contenant l'activité la plus récente ayant conduit au déclencheur.

Schéma illustrant le fonctionnement des instantanés de trace en arrière-plan, avec un tampon circulaire capturant les données avant un événement déclencheur.
Figure 1. Fonctionnement des instantanés de trace en arrière-plan

Définir un délai de refroidissement spécifique à un déclencheur

Les déclencheurs à haute fréquence peuvent rapidement consommer le quota du limiteur de débit de votre application. Pour éviter qu'un seul type de déclencheur n'épuise votre quota, utilisez setRateLimitingPeriodHours pour ajouter une période d'attente minimale par déclencheur en plus du limiteur de débit du système.

Déboguer des déclencheurs localement

Étant donné que les traces en arrière-plan s'exécutent à des intervalles aléatoires en production, pour tester les déclencheurs localement, vous devez forcer une trace en arrière-plan continue et contourner la limitation du débit au niveau du système pour votre package (tout délai de refroidissement par déclencheur défini avec setRateLimitingPeriodHours s'applique toujours, et rate_limiter.disabled ne s'applique qu'aux appels requestProfiling pilotés par l'application).

Pour connaître les commandes adb permettant de forcer les traces en arrière-plan, de simuler des déclencheurs à partir de la ligne de commande et d'inspecter l'état du service, consultez Activer de force les traces en arrière-plan pour les tests de déclencheurs dans Commandes de débogage pour le profilage local.