Triggerbasiertes Profiling

ProfilingManager unterstützt das Erfassen von Profilen basierend auf Systemtriggern. Das System verwaltet den Aufzeichnungsprozess und stellt Ihrer App das resultierende Profil zur Verfügung.

Trigger sind an leistungskritische Ereignisse gebunden. Vom System aufgezeichnete Profile enthalten detaillierte Debugging-Informationen für wichtiges Nutzerverhalten (Critical User Journey, CUJ), das mit diesen Triggern verknüpft ist.

Verlaufsdaten erfassen

Für viele Trigger müssen die Verlaufsdaten analysiert werden, die zum Ereignis führen. Der Trigger selbst ist oft eine Folge eines Problems und nicht die Ursache. Wenn Sie ein Profil erst nach dem Auslösen des Triggers starten, kann die Ursache bereits verloren sein.

Wenn beispielsweise ein Vorgang mit langer Ausführungszeit im UI-Thread ausgeführt wird, führt dies zu einem ANR-Fehler (Application Not Responding). Wenn das System den ANR-Fehler erkennt und die App benachrichtigt, ist der Vorgang möglicherweise bereits abgeschlossen. Wenn Sie ein Profil zu diesem Zeitpunkt starten, wird die eigentliche Blockierung nicht berücksichtigt.

Es ist nicht möglich, genau vorherzusagen, wann einige Trigger ausgelöst werden. Daher können Sie ein Profil nicht manuell im Voraus starten.

Warum sollte ich die triggerbasierte Erfassung verwenden?

Der Hauptgrund für die Verwendung von Profiler-Triggern ist das Erfassen von Daten für unvorhersehbare Ereignisse, bei denen eine App die Aufzeichnung nicht manuell starten kann, bevor diese Ereignisse eintreten. Profiler-Trigger können für Folgendes verwendet werden:

  • Leistungsprobleme beheben: ANRs, Speicherlecks und andere Stabilitätsprobleme diagnostizieren.
  • Wichtiges Nutzerverhalten optimieren: Analysieren und verbessern Sie Abläufe, z. B. den App-Start.
  • Nutzerverhalten analysieren: Sie erhalten Einblicke in Ereignisse wie von Nutzern initiierte App-Beendigungen.

Trigger einrichten

Der folgende Code zeigt, wie Sie sich für den Trigger TRIGGER_TYPE_APP_FULLY_DRAWN registrieren und eine Ratenbegrenzung darauf anwenden.

Kotlin

fun recordWithTrigger() {
    val profilingManager = applicationContext.getSystemService(ProfilingManager::class.java)

    val triggers = ArrayList<ProfilingTrigger>()

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

    triggers.add(triggerBuilder.build())

    val mainExecutor: 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(mainExecutor, resultCallback)
    profilingManager.addProfilingTriggers(triggers)

}
ProfilingManagerKotlinSnippets.kt

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 mainExecutor = 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(mainExecutor, resultCallback);
  profilingManager.addProfilingTriggers(triggers);

}
ProfilingManagerJavaSnippets.java

Der Code führt die folgenden Schritte aus:

  1. Manager abrufen: Ruft den ProfilingManager-Dienst ab.
  2. Trigger definieren: Erstellt einen ProfilingTrigger für TRIGGER_TYPE_APP_FULLY_DRAWN. Dieses Ereignis tritt auf, wenn die App meldet, dass sie gestartet wurde und interaktiv ist.
  3. Ratenbegrenzungen festlegen: Wendet eine Ratenbegrenzung von einer Stunde auf diesen bestimmten Trigger (setRateLimitingPeriodHours(1)) an. Dadurch wird verhindert, dass die App mehr als ein Startprofil pro Stunde aufzeichnet.
  4. Listener registrieren: Ruft registerForAllProfilingResults auf, um den Callback zu definieren, der das Ergebnis verarbeitet. Dieser Callback empfängt den Pfad des gespeicherten Profils über getResultFilePath().
  5. Trigger hinzufügen: Registriert die Triggerliste im ProfilingManager über addProfilingTriggers.
  6. Ereignis auslösen: Ruft reportFullyDrawn() auf, wodurch das Ereignis TRIGGER_TYPE_APP_FULLY_DRAWN an das System gesendet wird. Dadurch wird das Erfassen von Profilen ausgelöst, sofern ein System-Hintergrund-Trace ausgeführt wurde und ein Kontingent für die Ratenbegrenzung verfügbar ist. In diesem optionalen Schritt wird ein End-to-End-Ablauf demonstriert, da Ihre App für diesen Trigger reportFullyDrawn() aufrufen muss.

Trace abrufen

Das System speichert triggerbasierte Profile im selben Verzeichnis wie andere Profile. Der Dateiname für ausgelöste Traces hat folgendes Format:

profile_trigger_<profile_type_code>_<datetime>.<profile-type-name>

Sie können die Datei mit ADB abrufen. Wenn Sie beispielsweise den mit dem Beispielcode erfassten System-Trace mit ADB abrufen möchten, sieht das so aus:

adb pull /data/user/0/com.example.sampleapp/files/profiling/profile_trigger_1_2025-05-06-14-12-40.perfetto-trace
abrufen.

Weitere Informationen zum Visualisieren dieser Traces finden Sie unter Profilingdaten abrufen und analysieren.

So funktioniert die Hintergrundverfolgung

Um Daten von vor einem Trigger zu erfassen, startet das Betriebssystem regelmäßig einen Hintergrund-Trace. Wenn ein Trigger ausgelöst wird, während dieser Hintergrund-Trace aktiv ist und Ihre App dafür registriert ist, speichert das System das Trace-Profil im Verzeichnis Ihrer App. Das Profil enthält dann Informationen, die zum Auslösen des Triggers geführt haben.

Sobald das Profil gespeichert ist, benachrichtigt das System Ihre App über den Callback, der an registerForAllProfilingResults übergeben wurde. Dieser Callback enthält den Pfad zu dem erfassten Profil, auf das Sie mit ProfilingResult#getResultFilePath() zugreifen können.

Diagramm zur Funktionsweise von Hintergrund-Trace-Snapshots mit einem Ringpuffer, der Daten vor einem Triggerereignis erfasst.
Abbildung 1: Funktionsweise von Hintergrund-Trace-Snapshots

Um die Auswirkungen auf die Geräteleistung und die Akkulaufzeit zu minimieren, werden Hintergrund-Traces nicht kontinuierlich ausgeführt. Stattdessen wird eine Stichprobenmethode verwendet. Das System startet zufällig einen Hintergrund-Trace innerhalb eines festgelegten Zeitraums (mit einer Mindest- und Höchstdauer). Durch die zufällige Verteilung dieser Traces wird die Triggerabdeckung verbessert.

Systemausgelöste Profile haben eine vom System definierte maximale Größe. Daher wird ein Ringpuffer verwendet. Sobald der Puffer voll ist, überschreiben neue Trace-Daten die ältesten Daten. Wie in Abbildung 1 dargestellt, deckt ein erfasster Trace möglicherweise nicht die gesamte Dauer der Hintergrundaufzeichnung ab, wenn der Puffer voll ist. Stattdessen stellt er die letzten Aktivitäten dar, die zum Auslösen des Triggers geführt haben.

Triggerspezifische Ratenbegrenzung implementieren

Bei Triggern mit hoher Häufigkeit kann das Kontingent für die Ratenbegrenzung Ihrer App schnell aufgebraucht sein. Weitere Informationen zur Ratenbegrenzung finden Sie unter Funktionsweise der Ratenbegrenzung. Um zu verhindern, dass ein einzelner Triggertyp Ihr Kontingent aufbraucht, können Sie triggerbezogene Ratenbegrenzungen implementieren.

ProfilingManager unterstützt App-definierte triggerspezifische Ratenbegrenzungen. So können Sie zusätzlich zur vorhandenen Ratenbegrenzung eine weitere Ebene der zeitbasierten Drosselung hinzufügen. Mit der setRateLimitingPeriodHours API können Sie eine bestimmte Cooldown-Zeit für einen Trigger festlegen. Nach Ablauf der Wartezeit können Sie sie noch einmal auslösen.

Trigger lokal debuggen

Da Hintergrund-Traces zu zufälligen Zeiten ausgeführt werden, ist das Debuggen von Triggern lokal schwierig. Verwenden Sie den folgenden ADB-Befehl, um einen Hintergrund-Trace für Tests zu erzwingen:

adb shell device_config put profiling_testing system_triggered_profiling.testing_package_name <com.example.myapp>

Mit diesem Befehl wird das System gezwungen, einen kontinuierlichen Hintergrund-Trace für das angegebene Paket zu starten. So kann für jeden Trigger ein Profil erstellt werden, sofern die Ratenbegrenzung dies zulässt.

Sie können auch andere Debugging-Optionen aktivieren, z. B. die Ratenbegrenzung beim lokalen Debuggen deaktivieren. Weitere Informationen finden Sie unter Debugging-Befehle für das lokale Profiling.