Ab dem 27. März 2025 empfehlen wir, android-latest-release anstelle von aosp-main zu verwenden, um AOSP zu erstellen und Beiträge dazu zu leisten. Weitere Informationen finden Sie unter Änderungen am AOSP.

Diese Seite wurde von der Cloud Translation API übersetzt.

Trace-Suche

Sie können SQL verwenden, um bestimmte Status in Winscope Perfetto-Traces zu finden. Um Abfragen auszuführen und tabellarische Ergebnisse zu visualisieren, verwenden Sie den globalen Viewer Search in der Winscope-Benutzeroberfläche:

Viewer-Tab „Search“

Abbildung 1: Viewer-Tab „Search“

Im Viewer Search können Sie benutzerdefinierte SQL-Abfragen für Perfetto-Traces schreiben und ausführen sowie auf aktuelle und gespeicherte Abfragen zugreifen. Winscope bietet spezielle SQL-Ansichten, die bei der Suche nach SurfaceFlinger-, Transaktions-, Übergangs- und ViewCapture-Traces helfen.

Verwenden Sie für alle Ansichten die folgenden Konventionen:

Für die Spalten property und flat_property:
- Eigenschaftsnamen werden in Snake-Case-Schreibweise angegeben, z. B. visible_region aus LayerProto.
- Eine Punktnotation steht für verschachtelte Eigenschaften, z. B. visible_region.rect.
- Wiederkehrende Felder in property werden durch eckige Klammern unterschieden:
  
  In zwei Instanzen des wiederkehrenden Felds visible_region.rect wird das Feld top beispielsweise durch visible_region.rect[0].top und visible_region.rect[1].top dargestellt.
- Wiederkehrende Felder in flat_property sind nicht zu unterscheiden:
  
  In zwei Instanzen des wiederholten Felds visible_region.rect wird das Feld top beispielsweise in beiden Instanzen durch visible_region.rect.top dargestellt.
In den Spalten value und previous_value werden boolesche Werte durch 0 (False) oder 1 (True) dargestellt.

Winscope erstellt diese Ansichten, indem Daten aus spezifischen Tabellen mit der Perfetto-Tabelle args zusammengeführt werden. Sie können diese Tabellen direkt abfragen. In der Tabelle args entsprechen die Spalten key, flat_key und display_value den Ansichtsspalten property, flat_property und value.

args-Tabelle:

Spalte	Beschreibung
`arg_set_id`	Wird verwendet, um eine Reihe von Argumenten zuzuordnen.
`flat_key`	Eigenschaftsname aus der Proto-Nachricht, wobei wiederkehrende Felder nicht berücksichtigt werden
`key`	Eigenschaftsname aus der Proto-Nachricht, unter Berücksichtigung wiederkehrender Felder
`value_type`	Eigenschaftswerttyp
`int_value`	Eigenschaftswert, wenn der Werttyp eine Ganzzahl ist
`string_value`	Eigenschaftswert, wenn der Werttyp ein String ist
`real_value`	Eigenschaftswert, wenn der Werttyp „real“ ist
`display_value`	Eigenschaftswert in String umgewandelt

SurfaceFlinger-SQL-Ansichten

Für SurfaceFlinger-Protobuf-Daten werden die folgenden Formate verwendet:

Die Layerdaten haben das Format LayerProto.
Die Daten für die Hierarchiestammzelle haben das Format LayersSnapshotProto.

Um in Ebenendaten zu suchen, verwenden Sie die Ansicht sf_layer_search. Diese Ansicht enthält die folgenden Spalten:

Spalte	Beschreibung
`state_id`	Zeilen-ID des Eintrags, zu dem die Ebene gehört
`ts`	Zeitstempel des Eintrags, zu dem die Ebene gehört
`layer_id`	Ebenen-ID
`parent_id`	Ebenen-ID des übergeordneten Elements
`layer_name`	Name der Ebene
`is_visible`	Ebenensichtbarkeit
`property`	Eigenschaftsname, der wiederkehrende Felder berücksichtigt
`flat_property`	Im Eigenschaftsnamen werden keine wiederkehrenden Felder berücksichtigt
`value`	Eigenschaftswert im Stringformat
`previous_value`	Eigenschaftswert aus dem vorherigen Eintrag im Stringformat

Um nach Daten zu Hierarchie-Stammelementen zu suchen, verwenden Sie die Ansicht sf_hierarchy_root_search. Diese Ansicht enthält die folgenden Spalten:

Spalte	Beschreibung
`state_id`	Zeilen-ID des Eintrags
`ts`	Zeitstempel des Eintrags
`property`	Eigenschaftsname, der wiederkehrende Felder berücksichtigt
`flat_property`	Im Eigenschaftsnamen werden keine wiederkehrenden Felder berücksichtigt
`value`	Eigenschaftswert im Stringformat
`previous_value`	Eigenschaftswert aus dem vorherigen Eintrag im Stringformat

Beispielanfragen

Alle Frames finden, in denen die IME-Ebene sichtbar ist:

SELECT DISTINCT ts, layer_id, layer_name FROM sf_layer_search
  WHERE layer_name like 'IME%'
  AND is_visible=1

Alle Frames finden, in denen die IME-Ebene gültige Bildschirmgrenzen hat:

SELECT ts, value, previous_value FROM sf_layer_search
  WHERE layer_name like 'IME%'
  AND property='screen_bounds.bottom'
  AND value<='24000'

Alle Frames finden, in denen sich die Taskbar-Ebene color.a (Alpha) ändert:

SELECT ts, value, previous_value FROM sf_layer_search
  WHERE layer_name like 'Taskbar%'
  AND property='color.a'
  AND value!=previous_value

Alle Frames finden, in denen die Untergrenze von Wallpaper kleiner als oder gleich 2400 ist:

SELECT ts, value, previous_value FROM sf_layer_search
  WHERE layer_name LIKE 'Wallpaper%'
  AND property='bounds.bottom'
  AND cast_int!(value) <= 2400

Liste aller Eigenschaften für Displays mit einem gültigen Ebenen-Stack auflisten:

SELECT STATE.* FROM sf_hierarchy_root_search STATE_WITH_DISPLAY_ON
INNER JOIN sf_hierarchy_root_search STATE
  ON STATE.state_id = STATE_WITH_DISPLAY_ON.state_id
  AND STATE_WITH_DISPLAY_ON.flat_property='displays.layer_stack'
  AND STATE_WITH_DISPLAY_ON.value!='4294967295'
  AND STATE.property LIKE CONCAT(
    SUBSTRING(
        STATE_WITH_DISPLAY_ON.property,
        0,
        instr(STATE_WITH_DISPLAY_ON.property, ']')
    ),
    '%'
  )

Alle Frames finden, in denen die Wischgeste zum Zurückkehren sichtbar ist

SELECT DISTINCT STATE.ts FROM sf_layer_search STATE
  WHERE STATE.layer_name LIKE 'EdgeBackGestureHandler%'

Datentabellen

Die SurfaceFlinger-Ansichten werden mit den folgenden zugrunde liegenden Tabellen erstellt.

surfaceflinger_layers_snapshot:

Spalte	Beschreibung
`id`	Zeilen-ID für den Eintrag
`ts`	Zeitstempel des Eintrags
`arg_set_id`	ID, die verwendet wird, um Zeilen aus der Tabelle `args` mit diesem Eintrag zu verknüpfen

surfaceflinger_layer:

Spalte	Beschreibung
`id`	Zeilen-ID für die Ebene
`snapshot_id`	Zeilen-ID des Eintrags aus `surfaceflinger_layers_snapshot`, zu dem die Ebene gehört
`arg_set_id`	ID, die zum Verknüpfen von Zeilen aus der Tabelle `args` mit dieser Ebene verwendet wird

SQL-Ansicht „Transactions“

Für die Transaktions-Protobuf-Daten wird das Format TransactionTraceEntry verwendet.

Um in Transaktions-Trace-Daten zu suchen, verwenden Sie die Ansicht transactions_search. Diese Ansicht enthält die folgenden Spalten:

Spalte	Beschreibung
`state_id`	Zeilen-ID des Eintrags, zu dem die Proto-Eigenschaft gehört
`ts`	Zeitstempel des Eintrags, zu dem die Proto-Eigenschaft gehört
`transaction_id`	Transaktions-ID (falls verfügbar)
`property`	Eigenschaftsname, der wiederkehrende Felder berücksichtigt
`flat_property`	Im Eigenschaftsnamen werden keine wiederkehrenden Felder berücksichtigt
`value`	Eigenschaftswert im Stringformat

Beispielanfragen

Frame suchen, in dem eine Transaktion angewendet wurde, um die Position der Ebene X in -54.0 zu ändern:

SELECT ts, transaction_id, value FROM transactions_search
  WHERE flat_property='transactions.layer_changes.x'
  AND value='-54.0'

Frame suchen, in dem die ImeContainer-Ebene hinzugefügt wurde:

SELECT ts FROM transactions_search
  WHERE flat_property='added_layers.name'
  AND value='ImeContainer'

Datentabellen

Die SQL-Ansicht „Transactions“ wird mit den folgenden zugrunde liegenden Tabellen erstellt.

surfaceflinger_transactions:

Spalte	Beschreibung
`id`	Zeilen-ID für den Eintrag
`ts`	Zeitstempel des Eintrags
`arg_set_id`	ID, die verwendet wird, um Zeilen aus der Tabelle `args` mit diesem Eintrag zu verknüpfen
`vsync_id`	VSync-ID, die allen Transaktionen in diesem Eintrag zugeordnet ist

android_surfaceflinger_transaction:

Spalte	Beschreibung
`id`	Zeilen-ID für die Transaktion
`snapshot_id`	Zeilen-ID des Eintrags aus `surfaceflinger_transactions`, zu dem die Transaktion gehört
`arg_set_id`	ID, die verwendet wird, um Zeilen aus der Tabelle `args` mit dieser Transaktion zu verknüpfen
`transaction_id`	Transaktions-ID aus der Proto-Nachricht
`pid`	Transaktions-PID aus der Proto-Nachricht
`uid`	Transaktions-UID aus der Proto-Nachricht
`layer_id`	ID der Ebene, die mit der Transaktion verknüpft ist, falls zutreffend
`display_id`	ID des Displays, das mit der Transaktion verknüpft ist, falls zutreffend
`flags_id`	ID zum Abrufen zugehöriger Flags aus `android_surfaceflinger_transaction_flag`
`transaction_type`	Transaktionstyp

android_surfaceflinger_transaction_flag:

Spalte	Beschreibung
`flags_id`	Entspricht dem Wert in einer Zeile in `android_surfaceflinger_transaction`
`flag`	Übersetzter Flag-String

Einzelne Transaktionen werden der Tabelle „args“ aus verschiedenen Proto-Nachrichtenformaten hinzugefügt, je nach Transaktionstyp:

LAYER_ADDED: LayerCreationArgs-Format
LAYER_CHANGED: LayerState-Format
DISPLAY_ADDED: DisplayState-Format
DISPLAY_CHANGED: DisplayState-Format
LAYER_DESTROYED: Keine Argumente
LAYER_HANDLE_DESTROYED: Keine Argumente
DISPLAY_REMOVED: Keine Argumente
NOOP: Keine Argumente

SQL-Ansicht „Transitions“

Die Proto-Daten für Übergänge verwenden das Format ShellTransition.

Um in Übergangsdaten zu suchen, verwenden Sie die Ansicht transitions_search. Diese Ansicht enthält die folgenden Spalten:

Spalte	Beschreibung
`ts`	Zeit der Auslösung; falls verfügbar, wird auf die Sendezeit zurückgegriffen, andernfalls `0`
`transition_id`	Übergangs-ID aus der Proto-Nachricht
`property`	Eigenschaftsname, der wiederkehrende Felder berücksichtigt
`flat_property`	Im Eigenschaftsnamen werden keine wiederkehrenden Felder berücksichtigt
`value`	Transaktions-UID aus der Proto-Nachricht

Beispielanfragen

Eigenschaften von Übergängen, die von DefaultMixedHandler verarbeitet werden, finden:

  SELECT
    PROPS.ts,
    PROPS.transition_id,
    PROPS.property,
    PROPS.value
  FROM transitions_search HANDLER_MATCH
  INNER JOIN transitions_search PROPS
    ON HANDLER_MATCH.transition_id = PROPS.transition_id
  WHERE HANDLER_MATCH.property = 'handler'
    AND HANDLER_MATCH.value LIKE "%DefaultMixedHandler"
  ORDER BY PROPS.transition_id, PROPS.property

Datentabellen

Die Ansicht „Übergänge“ wird mit den folgenden zugrunde liegenden Tabellen erstellt.

window_manager_shell_transitions:

Spalte	Beschreibung
`id`	Zeilen-ID für den Übergang
`ts`	Zeit der Auslösung; falls verfügbar, wird auf die Sendezeit zurückgegriffen, andernfalls `0`
`transition_id`	Übergangs-ID aus der Proto-Nachricht
`arg_set_id`	ID, die verwendet wird, um Zeilen aus der Tabelle `args` mit diesem Übergang zu verknüpfen
`transition_type`	Übergangstyp aus der Proto-Nachricht
`send_time_ns`	Übergangs-Sendezeit aus der Proto-Nachricht
`dispatch_time_ns`	Zeitpunkt des Übergangs aus der Proto-Nachricht
`duration_ns`	Dauer des Übergangs, falls Start- und Endzeit verfügbar sind
`handler`	Übergangshandler: Übersetzung aus `window_manager_shell_transition_handlers` abrufen
`status`	Übergangsstatus: `played`, `merged` oder `aborted`
`flags`	Übergangs-Flags aus der Proto-Nachricht

window_manager_shell_transition_handlers:

Spalte	Beschreibung
`handler_id`	ID, die dem Wert in der Spalte `handler` von `window_manager_shell_transitions` entspricht
`handler_name`	String-Übersetzung

android_window_manager_shell_transition_participants:

Spalte	Beschreibung
`transition_id`	Übergangs-ID aus der Roh-Proto-Nachricht
`layer_id`	ID des SurfaceFlinger-Layer-Teilnehmers
`window_id`	ID des WindowManager-Containerteilnehmers

SQL-Ansicht „ViewCapture“

Die ViewCapture-Protobuf-Daten verwenden das Format View.

Um in ViewCapture-Daten zu suchen, verwenden Sie die Ansicht viewcapture_search. Diese Ansicht enthält die folgenden Spalten:

Spalte	Beschreibung
`state_id`	Zeilen-ID des Bundesstaats, zu dem die Ansicht gehört
`ts`	Zeitstempel des Status, zu dem die Ansicht gehört
`package_name`	Paketname
`window_name`	Name des Fensters
`class_name`	Kursname ansehen
`property`	Eigenschaftsname, der wiederkehrende Felder berücksichtigt
`flat_property`	Im Eigenschaftsnamen werden keine wiederkehrenden Felder berücksichtigt
`value`	Eigenschaftswert im Stringformat
`previous_value`	Eigenschaftswert aus dem vorherigen Status im Stringformat

Beispielanfragen

Alle Zustände finden, in denen sich SearchContainerView in Y-Richtung bewegt hat:

  SELECT * FROM viewcapture_search
  WHERE class_name LIKE '%SearchContainerView'
    AND flat_property='translation_y'
    AND value!=previous_value

Datentabellen

Die Ansicht „ViewCapture“ wird mit den folgenden zugrunde liegenden Tabellen erstellt.

android_viewcapture:

Spalte	Beschreibung
`id`	Zeilen-ID für den Eintrag
`ts`	Zeitstempel des Eintrags
`arg_set_id`	ID, die verwendet wird, um Zeilen aus der Tabelle `args` mit diesem Eintrag zu verknüpfen

android_viewcapture_view:

Spalte	Beschreibung
`id`	Zeilen-ID für die Ansicht
`snapshot_id`	Zeilen-ID des Eintrags aus `android_viewcapture`, zu dem die Ansicht gehört
`arg_set_id`	ID, die zum Verknüpfen von Zeilen aus der Tabelle `args` mit dieser Ansicht verwendet wird

ProtoLog-SQL-Tabelle

Die ProtoLog-Protodaten verwenden das Format ProtoLogMessage. Diese Ansicht enthält die folgenden Spalten:

Spalte	Beschreibung
`ts`	Zeitstempel des Logs
`level`	Protokollebene
`tag`	Tag für die Protokollierungsgruppe
`message`	Logeintrag
`stacktrace`	Stacktrace (falls verfügbar)
`location`	Code-Speicherort, von dem die Nachricht stammt

Beispielanfragen

Alle Logs mit einer Nachricht finden, die transition enthält:

SELECT ts, message, location FROM protolog
  WHERE message LIKE '%transition%'

Alle Logs mit gültigen Transaktions-IDs finden:

CREATE PERFETTO VIEW valid_tx_ids AS
  SELECT DISTINCT transaction_id FROM transactions_search
  WHERE transaction_id IS NOT NULL AND transaction_id != '0';

SELECT TRANS.transaction_id, message FROM valid_tx_ids TRANS
INNER JOIN protolog LOGS
  ON LOGS.message LIKE CONCAT('%', TRANS.transaction_id, '%');

WindowManager-SQL-Ansicht

Die WindowManager-Protobuf-Daten verwenden das hierarchische Format WindowManagerServiceDumpProto. Sie können nach Attributen eines beliebigen WindowManager-Containers suchen, z. B.:

Um in WindowManager-Daten zu suchen, verwenden Sie die Ansicht wm_search. Diese Ansicht enthält die folgenden Spalten:

Spalte	Beschreibung
`state_id`	Zeilen-ID des Bundesstaats, zu dem der Container gehört
`ts`	Zeitstempel des Status, zu dem der Container gehört
`title`	Containertitel
`token`	Container-Token
`parent_token`	Übergeordnetes Container-Token
`is_visible`	Sichtbarkeit von Containern
`property`	Eigenschaftsname, der wiederkehrende Felder berücksichtigt
`flat_property`	Im Eigenschaftsnamen werden keine wiederkehrenden Felder berücksichtigt
`value`	Eigenschaftswert im Stringformat
`previous_value`	Eigenschaftswert aus dem vorherigen Status im Stringformat

Beispielanfragen

Alle Bundesstaaten finden, in denen LauncherActivity sichtbar ist:

SELECT DISTINCT ts, title, token FROM wm_search
  WHERE title like '%LauncherActivity%'
  AND is_visible=1

Alle Zustände finden, in denen sich die Oberfläche des Wallpaper bewegt:

SELECT ts, value, previous_value FROM wm_search
  WHERE title like '%Wallpaper%'
  AND property like '%surface_position%'
  AND value != previous_value

Datentabellen

Die WindowManager-Ansicht wird mit den folgenden zugrunde liegenden Tabellen erstellt.

android_windowmanager:

Spalte	Beschreibung
`id`	Zeilen-ID für den Eintrag
`ts`	Zeitstempel des Eintrags
`arg_set_id`	ID, die verwendet wird, um Zeilen aus der Tabelle `args` mit diesem Eintrag zu verknüpfen

android_windowmanager_windowcontainer:

Spalte	Beschreibung
`id`	Zeilen-ID für den Container
`snapshot_id`	Zeilen-ID des Eintrags aus `android_windowmanager`, zu dem der Container gehört
`arg_set_id`	ID, die zum Verknüpfen von Zeilen aus der Tabelle `args` mit dieser Ansicht verwendet wird

Abfragen ausführen

Sie können Suchanfragen über den Bereich GLOBALE SUCHE links im Such-Viewer ausführen.

Wenn Sie zum ersten Mal mit dem Bereich GLOBAL SEARCH interagieren, wird die Trace-Suche initialisiert und Winscope erstellt die SQL-Hilfsansichten. Das dauert einige Sekunden. Während die Tracesuche initialisiert wird, ist die Zeitachse nicht verfügbar.

Um eine Anfrage zu starten, geben Sie eine Anfrage in das Suchfeld ein und klicken Sie auf Suchanfrage ausführen oder drücken Sie die Eingabetaste auf der Tastatur.

Wenn Sie fertig sind, wird die Ergebnistabelle im mittleren Bereich angezeigt. Ihre Anfrage wird unter dem Suchfeld angezeigt. Dort befindet sich auch ein Feld, in dem Sie die Anfrage für spätere Sitzungen speichern können.

Auf gespeicherte Abfragen können Sie zugreifen, indem Sie im linken Bereich auf den Tab Gespeichert klicken. Auf zuletzt ausgeführte Abfragen können Sie zugreifen, indem Sie auf den Tab Letzte klicken:

Linker Bereich des Viewer-Tabs „Search“

Abbildung 2: Linkes Steuerfeld des Viewers für die Suche

Ergebnisse

Alle Abfragen geben tabellarische Ergebnisse zurück, die in einer scrollbaren Ansicht mit interaktivem Verhalten angezeigt werden, das dem der logbasierten Trace-Viewer ähnelt, z. B. „Transaktionen“ und „ProtoLog“:

Suchergebnisse ansehen

Abbildung 3: Suchergebnisse ansehen

Wenn die resultierende Tabelle eine Spalte ts enthält, werden die Werte in dieser Spalte als Zeitstempel interpretiert und dem Zeitachsen-Overlay als neue Zeile mit Einträgen hinzugefügt. Klicken Sie auf diese Zeile und verwenden Sie den Links- und Rechtspfeil, um zwischen den Einträgen zu wechseln:

Suchzeitachse

Abbildung 4: Suchzeitachse.

Trace-Suche Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

SurfaceFlinger-SQL-Ansichten

Beispielanfragen

Datentabellen

SQL-Ansicht „Transactions“

Beispielanfragen

Datentabellen

SQL-Ansicht „Transitions“

Beispielanfragen

Datentabellen

SQL-Ansicht „ViewCapture“

Beispielanfragen

Datentabellen

ProtoLog-SQL-Tabelle

Beispielanfragen

WindowManager-SQL-Ansicht

Beispielanfragen

Datentabellen

Abfragen ausführen

Ergebnisse

Trace-Suche