Debug-Befehle für die lokale Profilerstellung

Wenn Sie Ihre ProfilingManager-Integration lokal testen, werden Anfragen möglicherweise durch die Ratenbegrenzung gedrosselt oder Hintergrund-Traces sind beim Testen von Triggern möglicherweise nicht aktiv. Mit den adb-Befehlen auf dieser Seite können Sie die Drosselung deaktivieren, Profile abrufen, nicht bearbeitete Traces beibehalten, Erfassungen auslösen und den Dienststatus auf einem Testgerät prüfen.

Ratenbegrenzung deaktivieren

Führen Sie den folgenden device_config-Befehl aus, um die App-Prozess- und System-Ratenbegrenzungen für requestProfiling-Anfragen während lokaler Tests zu deaktivieren:

adb shell device_config put profiling_testing rate_limiter.disabled true

Wenn Sie mit dem Testen fertig sind, setzen Sie das Flag zurück:

adb shell device_config delete profiling_testing rate_limiter.disabled

Profile mit ADB abrufen

Wenn Sie ein bearbeitetes Profil lokal auf einem Gerät mit Root-Zugriff prüfen möchten, führen Sie adb pull mit dem von getResultFilePath zurückgegebenen Pfad aus:

# Pull a profile
adb pull /data/user/0/<com.example.myapp>/files/profiling/<profile-file-name>

Temporäre und nicht entfernte Ergebnisse beibehalten

Wenn Sie die Profilerstellung lokal testen, können Sie die Ergebnisse im temporären Verzeichnis unter /data/misc/perfetto-traces/profiling/ beibehalten. Wenn Sie einen nicht entfernten System-Trace mit dem entfernten Pendant vergleichen, können Sie nachvollziehen, welche Daten beim Entfernen gelöscht werden.

Wie temporäre und nicht bearbeitete Ergebnisse aufbewahrt werden, hängt von der Android-Version Ihres Geräts ab:

  • Android 16 (API-Level 36) und höher: Sie können sowohl nicht bearbeitete (falls zutreffend) als auch bearbeitete Ergebnisse im temporären Verzeichnis beibehalten. Dieses Verzeichnis wurde in Android 16 erweitert, sodass es auf allen Build-Typen ohne Root-Zugriff über adb pull zugänglich ist. In Android 15 ist dagegen Root-Zugriff erforderlich, um /data/misc/perfetto-traces/profiling/ zu lesen. Führen Sie den folgenden Befehl aus, um zu verhindern, dass das System temporäre Ergebnisse löscht:

    adb shell device_config put profiling_testing delete_temporary_results.disabled true

  • Android 15 (API-Level 35): Im temporären Verzeichnis können Sie nur das nicht geschwärzte Ergebnis beibehalten, auf das nur in Builds mit Root-Zugriff über adb zugegriffen werden kann. (Ihre App erhält das bearbeitete Profil weiterhin im eigenen Verzeichnis /data/user/0/<app>/files/profiling/, das Ihr App-Code bei jedem Build lesen oder kopieren kann. Wenn Sie es jedoch direkt mit adb pull aus /data/user/0/... abrufen möchten, ist Root-Zugriff erforderlich, oder adb shell run-as <app> bei einem debugfähigen Build.) Führen Sie den folgenden Befehl aus, um zu verhindern, dass das System nicht entfernte Traces löscht:

    adb shell device_config put profiling_testing delete_unredacted_trace.disabled true

Nachdem Sie ein Profil erfasst haben, rufen Sie die beibehaltene Datei aus dem temporären Verzeichnis ab:

# Pull a retained redacted profile (Android 16 and higher)
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.<profile-type-ext>

# Pull an unredacted system trace
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.perfetto-trace-unredacted

In diesen Befehlen ist <trace-name> der Basisdateiname (ohne Erweiterung) aus dem von ProfilingResult.getResultFilePath zurückgegebenen Pfad. Die nicht bearbeitete Kopie des System-Traces hängt -unredacted an die Erweiterung .perfetto-trace an. Weitere Informationen zur Dateinamensstruktur und zu den <profile-type-ext>-Werten finden Sie unter Dateispeicherorte und Namensformate.

adb shell device_config delete profiling_testing delete_temporary_results.disabled
adb shell device_config delete profiling_testing delete_unredacted_trace.disabled

Hintergrund-Traces für Triggertests zwingend aktivieren

Da Systemhintergrund-Traces in der Produktion in zufälligen Intervallen ausgeführt werden, kann es schwierig sein, triggerbasiertes Profiling lokal zu testen. Wenn Sie das System zwingen möchten, einen kontinuierlichen Hintergrund-Trace auszuführen und die Ratenbegrenzung auf Systemebene für die Trigger Ihrer App zu umgehen, legen Sie system_triggered_profiling.testing_package_name fest:

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

Alle mit setRateLimitingPeriodHours konfigurierten Cooldown-Zeiten pro Trigger gelten weiterhin. Da dieser Modus so lange ausgeführt wird, bis Sie ihn beenden, sollten Sie das Flag entfernen, wenn Sie mit dem Testen fertig sind:

adb shell device_config delete profiling_testing system_triggered_profiling.testing_package_name

Nützliche Befehle zur Fehlerbehebung

Unter Android 16 (API-Level 36) und höher mit einer aktuellen Version des Profiling-Moduls können Sie das cmd profiling_service-Tool über adb verwenden, um das ausführliche Logging zu aktivieren, On-Demand-Profilsammlungen auszulösen und Trigger direkt über die Befehlszeile zu testen.

Ausführliches Debugging-Logging aktivieren

Führen Sie den folgenden Befehl aus, um detaillierte ProfilingService-Logs in logcat zu aktivieren und die Verarbeitung und Bereitstellung von Anfragen zu diagnostizieren:

adb shell cmd profiling_service enable-logs true

On-Demand-Profilerfassung anfordern

Führen Sie den folgenden Befehl aus, um eine sofortige Profilerfassung für ein bestimmtes Paket über die Befehlszeile zu starten:

adb shell cmd profiling_service request-profiling <profiling_type> <com.example.myapp> [--user <user_id>] [--duration <duration_ms>] [--sources <sources>]

In diesem Befehl ist <profiling_type> der ganzzahlige konstante Wert aus ProfilingManager (1 für einen Java-Heap-Dump, 2 für ein Heap-Profil, 3 für Stack-Sampling oder 4 für einen System-Trace). Der Ziel-App-Prozess muss für Speicher- und Stack-Profile ausgeführt werden. Die Anfrage unterliegt der Ratenbegrenzung, sofern diese nicht deaktiviert ist, und das abgeschlossene ProfilingResult wird nur an globale Listener gesendet, die bei registerForAllProfilingResults registriert sind.

Trigger registrieren und simulieren

Führen Sie die folgenden Befehle aus, um einen Trigger zu registrieren oder ein simuliertes Triggerereignis für ein Paket auszulösen und die Verarbeitung des Trigger-Callbacks zu prüfen:

adb shell cmd profiling_service add-trigger <trigger_type> <com.example.myapp> [--user <user_id>]
adb shell cmd profiling_service trigger <trigger_type> <com.example.myapp> [--user <user_id>]

In diesen Befehlen ist <trigger_type> der ganzzahlige konstante Wert aus ProfilingTrigger (z. B. 1 für TRIGGER_TYPE_APP_FULLY_DRAWN, 2 für TRIGGER_TYPE_ANR oder 7 für TRIGGER_TYPE_OOM). Wenn Sie add-trigger ausführen, wird der Trigger mit einer 0-stündigen Cooldown-Phase registriert, wodurch alle vorhandenen Registrierungen für diesen Triggertyp überschrieben werden. Zum Simulieren von Triggern, die einen Snapshot des Hintergrund-Trace speichern (z. B. 1 oder 2), ist ein aktiver Hintergrund-Trace erforderlich (siehe Hintergrund-Traces für Triggertests zwingend aktivieren).

Gesamtstatus von ProfilingManager erfassen

Unter Android 16 (API-Level 36) und höher mit einer aktuellen Version des Profiling-Moduls können Sie dumpsys für profiling_service ausführen, um Probleme zu diagnostizieren und den aktuellen Status von ProfilingManager zu prüfen:

adb shell dumpsys profiling_service

Die Ausgabe von dumpsys profiling_service dient nur zu Informations- und Debugging-Zwecken. Das Format kann sich ändern. Sie bietet einen Snapshot des internen Status des Dienstes, einschließlich:

  • Aktive Drosselungen und Status der Ratenbegrenzung.
  • Aktive Gerätekonfigurationen.
  • Registrierte App-Trigger und ihre Abkühlzeiten für die Ratenbegrenzung.
  • Aktive Profilerstellungssitzungen und solche in der Warteschlange.
  • Letzte Profiling-Anfragen, Trigger-Vorkommen und Ereignisse zur Ergebnisbereitstellung.