System-Trace auf einem Gerät erfassen

Geräte mit Android 9 (API-Level 28) oder höher haben eine App auf Systemebene namens „System-Tracing“. Diese App ähnelt dem Befehlszeilen-Dienstprogramm systrace. Mit ihr können Sie jedoch direkt auf einem Testgerät Protokolle aufzeichnen, ohne das Gerät anschließen und über adb eine Verbindung dazu herstellen zu müssen. Mit der App können Sie die Ergebnisse dieser Traces dann mit Ihrem Entwicklungsteam teilen.

Auf Geräten mit Android 10 und höher werden Traces im Perfetto-Format aufgezeichnet, während sie auf älteren Geräten im Systrace-Format aufgezeichnet werden. Wir empfehlen, den Perfetto-Trace Viewer zu verwenden, um beide Formate zu öffnen und dann die Traces zu analysieren.

Es ist hilfreich, Traces aufzuzeichnen, wenn Sie leistungsbezogene Fehler in Ihrer App beheben, z. B. langsame Starts, langsame Übergänge oder Ruckler in der Benutzeroberfläche.

System-Trace aufzeichnen

Mit der App „System-Tracing“ können Sie einen System-Trace über die Schnelleinstellung oder ein Menü in der App aufzeichnen. In den folgenden Abschnitten wird beschrieben, wie Sie die Aufzeichnung mithilfe dieser Oberflächen abschließen.

Hinweis :Im Rahmen Ihres Entwicklungsworkflows können Sie einen On-Device-Fehlerbericht einreichen. Es ist wichtig, diese Art von Fehlerbericht einzureichen, nachdem Sie die Aufzeichnung eines System-Traces abgeschlossen haben. So ist der Prozess zum Erstellen des Fehlerberichts nicht im aufgezeichneten Trace enthalten.

Über die Kachel „Schnelleinstellungen“ aufzeichnen

Die Kachel „Schnelleinstellungen“ ist in der Regel die praktischere Möglichkeit, die Systemaufzeichnung auf dem Gerät durchzuführen.

Kachel einrichten

Wenn Sie die Systemaufzeichnung zum ersten Mal auf Ihrem Testgerät verwenden oder die Kachel Systemaufzeichnung nicht in den Schnelleinstellungen Ihres Geräts sehen (siehe Abbildung 2), führen Sie die folgenden Einrichtungsschritte aus:

1. Aktivieren Sie die Entwickleroptionen.
2. Öffnen Sie den Einstellungsbildschirm Entwickleroptionen.
3. Wählen Sie im Bereich Debugging die Option System-Tracing aus. Die Systemaufzeichnung wird geöffnet und das App-Menü wird angezeigt.

4. Aktivieren Sie im App-Menü die Option Schnelleinstellungen-Kachel anzeigen, wie in Abbildung 1 dargestellt. Das System fügt dem Bereich Schnelleinstellungen die Kachel System-Tracing hinzu, wie in Abbildung 2 dargestellt:

   

   Abbildung 1: Der Schalter Schnelleinstellungen-Kachel für das Tracing anzeigen in der App „System-Tracing“.

   

   Abbildung 2. Die Kachel System-Tracing im Bereich Schnelleinstellungen

   Hinweis:Standardmäßig wird die Kachel Systemaufzeichnung als erste Kachel im Bereich Schnelleinstellungen hinzugefügt. Wenn Sie möchten, dass die Kachel an einer anderen Position angezeigt wird, verschieben Sie sie im Bearbeitungsmodus des Steuerfelds.

Systemaufzeichnung durchführen

So zeichnen Sie einen System-Trace mit dem Bereich Schnelleinstellungen auf:

1. Tippen Sie auf die Kachel Systemaufzeichnung mit dem Label Aufzeichnung erfassen. Die Kachel wird aktiviert und eine dauerhafte Benachrichtigung wird angezeigt, dass das System einen Trace aufzeichnet (siehe Abbildung 3):

   

   Abbildung 3: Dauerhafte Benachrichtigung, die nach dem Starten eines On-Device-System-Traces angezeigt wird.

2. Führen Sie in Ihrer App die Aktionen aus, die das System prüfen soll.

   Hinweis :Sie können schwer zu reproduzierende Fehler aufzeichnen, indem Sie das System-Tracing im Hintergrund laufen lassen und es kurz nach dem Auftreten des Fehlers beenden. Bei der Systemaufzeichnung werden die Aktivitäten eines Geräts in einem zyklischen Puffer gespeichert, der 10 bis 30 Sekunden an Ereignissen enthält.

3. Tippen Sie entweder auf die Kachel Systemaufzeichnung im Bereich Schnelleinstellungen oder auf die Benachrichtigung „Systemaufzeichnung“, um die Aufzeichnung zu beenden.

   Das System zeigt eine neue Benachrichtigung mit der Meldung „Trace wird gespeichert“ an. Wenn der Vorgang abgeschlossen ist, schließt das System die Benachrichtigung und zeigt eine dritte Benachrichtigung an, in der bestätigt wird, dass der Ablauf protokolliert wurde und Sie den System-Trace freigeben können (siehe Abbildung 4):

   

   Abbildung 4: Dauerhafte Benachrichtigung, die angezeigt wird, nachdem das System die Aufzeichnung eines Protokolls abgeschlossen hat.

Aufzeichnung über das App-Menü

Im App-Menü können Sie mehrere erweiterte Einstellungen für das System-Tracing konfigurieren. Außerdem gibt es einen Schalter zum Starten und Beenden eines System-Traces.

So zeichnen Sie einen System-Trace mit dem Menü der System-Tracing-App auf:

1. Aktivieren Sie die Entwickleroptionen.

2. Öffnen Sie den Einstellungsbildschirm Entwickleroptionen. Wählen Sie im Bereich Debugging die Option System-Tracing aus. Die System-Tracing-App wird geöffnet.

   Wenn Sie die Kachel Systemaufzeichnung eingerichtet haben, können Sie sie auch gedrückt halten, um die Systemaufzeichnungs-App aufzurufen.

3. Achten Sie darauf, dass Debugfähige Anwendungen erfassen ausgewählt ist, damit Apps, für die das Debugging aktiviert ist, in den System-Trace aufgenommen werden.

4. Optional können Sie die Kategorien der zu erfassenden System- und Sensoraufrufe auswählen und eine CPU-spezifische Puffergröße in KB festlegen. Wählen Sie Kategorien aus, die dem zu testenden Anwendungsfall entsprechen, z. B. die Kategorie Audio zum Testen von Bluetooth-Vorgängen oder die Kategorie Speicher für Heap-Zuweisungen.

   Hinweis :Diese Kategorien dienen als Einstellungen auf App-Ebene. Sie werden daher auch vom System verwendet, wenn die Kachel Schnelleinstellungen verwendet wird. Außerdem bleiben diese Einstellungen auch nach einem Neustart des Geräts erhalten.

5. Optional können Sie Lange Traces auswählen, um Traces zu aktivieren, die fortlaufend im Gerätespeicher gespeichert werden. Legen Sie für diese Option Limits für die Maximale Größe von Long Traces und die Maximale Dauer von Long Traces fest.

6. Aktivieren Sie den Schalter Aufzeichnung erfassen, der in Abbildung 5 hervorgehoben ist. Die Kachel wird aktiviert und eine dauerhafte Benachrichtigung wird angezeigt, dass das System einen Trace aufzeichnet, wie in Abbildung 3 dargestellt.

   

   Abbildung 5. Über den Schalter Trace aufzeichnen in den System-Tracing-Einstellungen.

7. Führen Sie in Ihrer App die Aktionen aus, die das System prüfen soll.

   Hinweis :Sie können schwer zu reproduzierende Fehler aufzeichnen, indem Sie das System-Tracing im Hintergrund laufen lassen und es kurz nach dem Auftreten des Fehlers beenden. Standardmäßig speichert das System-Tracing die Aktivitäten eines Geräts in einem zyklischen Puffer, der 10 bis 30 Sekunden an Ereignissen enthält. Wenn Lange Traces aktiviert ist, werden die Aktivitäten des Geräts bis zu den von Ihnen festgelegten Limits kontinuierlich im Gerätespeicher gespeichert.

8. Deaktivieren Sie den Schalter Aufzeichnung erfassen, um das Tracing zu beenden.

   Das System zeigt eine neue Benachrichtigung mit der Meldung „Trace wird gespeichert“ an. Wenn der Vorgang abgeschlossen ist, schließt das System die Benachrichtigung und zeigt eine dritte Benachrichtigung an, in der bestätigt wird, dass der Ablauf protokolliert wurde und Sie den System-Trace freigeben können (siehe Abbildung 4).

System-Trace teilen

Mit der System-Tracing-App können Sie System-Tracing-Ergebnisse im Rahmen verschiedener Workflows freigeben. Auf einem Gerät mit Android 10 (API-Level 29) oder höher werden Tracedateien mit der Dateiendung .perfetto-trace gespeichert und können in der Perfetto-Benutzeroberfläche geöffnet werden. Auf einem Gerät mit einer älteren Android-Version werden Trace-Dateien mit der Dateinamenserweiterung .ctrace gespeichert, was dem Systrace-Format entspricht.

Als Nachricht teilen

Mit dem System-Tracing können Sie die erfassten Protokolle mit anderen Apps auf Ihrem Gerät teilen. Sie können den Trace per E-Mail oder über eine Bug-Tracking-App an Ihr Entwicklungsteam senden, ohne ein Gerät an Ihren Entwicklungscomputer anschließen zu müssen.

Nachdem Sie einen System-Trace aufgezeichnet haben, tippen Sie auf die Benachrichtigung, die auf dem Gerät angezeigt wird, wie in Abbildung 4 dargestellt. Die Intent-Auswahl der Plattform wird angezeigt. Sie können den Trace dann über die Nachrichten-App Ihrer Wahl teilen.

Über die Files App teilen

Auf Geräten mit Android 10 (API-Level 29) oder höher werden Traces in der Dateien App angezeigt. Sie können einen Trace über diese App freigeben.

Bericht mit ADB herunterladen

Sie können einen System-Trace auch mit adb von einem Gerät extrahieren. Verbinden Sie das Gerät, mit dem Sie den Trace aufgezeichnet haben, mit Ihrem Entwicklungscomputer und führen Sie dann die folgenden Befehle in einem Terminalfenster aus:

cd /path-to-traces-on-my-dev-machine && \
  adb pull /data/local/traces/ .

Zwischen Trace-Formaten konvertieren

Sie können Perfetto-Protokolldateien in das Systrace-Format konvertieren. Weitere Informationen finden Sie unter Zwischen Trace-Formaten konvertieren.

HTML-Bericht erstellen

Wenn Sie den Ablauf teilen, befindet sich der Bericht auf Geräten mit Android 10 oder höher in einer .perfetto-trace-Datei und auf allen anderen Versionen in einer .ctrace-Datei.

Erstellen Sie einen HTML-Bericht aus der Tracedatei mithilfe einer webbasierten Benutzeroberfläche oder über die Befehlszeile.

Webbasierte Benutzeroberfläche

Öffnen Sie die Tracedatei und generieren Sie den Bericht über die Perfetto-Benutzeroberfläche.

Klicken Sie bei einer Perfetto-Datei auf Trace-Datei öffnen. Klicken Sie bei einer Systrace-Datei auf Mit der alten Benutzeroberfläche öffnen. Die alte Benutzeroberfläche hat dasselbe Erscheinungsbild wie der Systrace-Bericht.

Befehlszeile

Führen Sie die folgenden Befehle in einem Terminalfenster aus, um einen HTML-Bericht aus der Tracedatei zu generieren:

cd /path-to-traces-on-my-dev-machine && \
  systrace --from-file trace-file-name{.ctrace | .perfetto-trace}

Wenn Sie das Befehlszeilenprogramm systrace noch nicht haben, können Sie es aus dem Catapult-Projekt auf GitHub oder direkt aus dem Android Open Source Project herunterladen.