Trace-Suche

Mit SQL können Sie in Winscope-Perfetto-Traces nach bestimmten Status suchen. Verwenden Sie die globale Suche in der Winscope-Benutzeroberfläche, um Abfragen auszuführen und tabellarische Ergebnisse zu visualisieren:

Tab „Betrachter der Suche“

Abbildung 1: Tab „Suchanfragen“

Mit der Suche 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 die Suche in SurfaceFlinger-, Transaktions-, Übergangs- und ViewCapture-Traces erleichtern.

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.
    • Die Punktnotation steht für verschachtelte Properties, 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 Property-Name aus der Proto-Nachricht, ohne Berücksichtigung von wiederholten Feldern
key Property-Name aus der Proto-Nachricht, wobei wiederholte Felder berücksichtigt werden
value_type Attributwerttyp
int_value Attributwert, wenn der Werttyp eine Ganzzahl ist
string_value Property-Wert, wenn der Werttyp ein String ist
real_value Property-Wert, wenn der Werttyp „real“ ist
display_value Attributwert als String

SurfaceFlinger-SQL-Ansichten

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

Verwenden Sie die Ansicht sf_layer_search, um nach Layerdaten zu suchen. 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
property Property-Name unter Berücksichtigung wiederkehrender Felder
flat_property Property-Name ohne Berücksichtigung wiederholter Felder
value Attributwert im Stringformat
previous_value Property-Wert aus dem vorherigen Eintrag im Stringformat

Verwenden Sie die Ansicht sf_hierarchy_root_search, um nach Daten des Hierarchiestamms zu suchen. Diese Ansicht enthält die folgenden Spalten:

Spalte Beschreibung
state_id Zeilen-ID des Eintrags
ts Zeitstempel des Eintrags
property Property-Name unter Berücksichtigung wiederkehrender Felder
flat_property Property-Name ohne Berücksichtigung wiederholter Felder
value Attributwert im Stringformat
previous_value Property-Wert aus dem vorherigen Eintrag im Stringformat

Beispielanfragen

  • Alle Frames suchen, in denen die Ebene IME 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 suchen, in denen sich die Ebene Taskbar 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 suchen, 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
    
  • Alle Eigenschaften für Displays mit einem gültigen Layer-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 für Transaktionen

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

Verwenden Sie die Ansicht transactions_search, um nach Trace-Daten für Transaktionen zu suchen. Diese Ansicht enthält die folgenden Spalten:

Spalte Beschreibung
state_id Zeilen-ID des Eintrags, zu dem die Proto-Property gehört
ts Zeitstempel des Eintrags, zu dem das Proto-Attribut gehört
transaction_id Transaktions-ID (falls verfügbar)
property Property-Name unter Berücksichtigung wiederkehrender Felder
flat_property Property-Name ohne Berücksichtigung wiederholter Felder
value Attributwert im Stringformat

Beispielanfragen

  • Suchen Sie den Frame, in dem eine Transaktion angewendet wurde, um die X-Position der Ebene auf -54,0 zu ändern:

    SELECT ts, transaction_id, value FROM transactions_search
      WHERE flat_property='transactions.layer_changes.x'
      AND value='-54.0'
    
  • Suchen Sie den Frame, in dem der Layer ImeContainer 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 Proto-Nachricht
pid Transaktions-PID aus Proto-Nachricht
uid Transaktions-UID aus Proto-Nachricht
layer_id ID der mit der Transaktion verknüpften Ebene, falls zutreffend
display_id ID der mit der Transaktion verknüpften Anzeige, 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 für Übergänge

Die Übergangs-Protobuf-Daten verwenden das Format ShellTransition.

Verwenden Sie die Ansicht transitions_search, um nach Daten zu Übergängen zu suchen. Diese Ansicht enthält die folgenden Spalten:

Spalte Beschreibung
ts Zeit der Auslösung; wird auf die Sendezeit zurückgesetzt, falls verfügbar, andernfalls 0
transition_id Übergangs-ID aus der Proto-Nachricht
property Property-Name unter Berücksichtigung wiederkehrender Felder
flat_property Property-Name ohne Berücksichtigung wiederholter Felder
value Transaktions-UID aus 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 anhand der folgenden zugrunde liegenden Tabellen erstellt.

window_manager_shell_transitions:

Spalte Beschreibung
id Zeilen-ID für den Übergang
ts Zeit der Auslösung; wird auf die Sendezeit zurückgesetzt, falls verfügbar, 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 Übergangszeit aus Proto-Nachricht übernehmen
dispatch_time_ns Übergangs-Dispatch-Zeit 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 Status des Übergangs: 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

ViewCapture-SQL-Ansicht

Die ViewCapture-Protobuf-Daten verwenden das Format View.

Verwenden Sie die Ansicht viewcapture_search, um nach ViewCapture-Daten zu suchen. 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 Property-Name unter Berücksichtigung wiederkehrender Felder
flat_property Property-Name ohne Berücksichtigung wiederholter Felder
value Attributwert im Stringformat
previous_value Eigenschaftswert aus dem vorherigen Status im Stringformat

Beispielanfragen

Alle Status 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 ViewCapture-Ansicht 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, '%');
    

Abfragen ausführen

Sie können Suchanfragen über den Bereich GLOBALE SUCHE links im Suchfenster 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 der Suchansicht

Abbildung 2: Suchbereich im linken Bereich.

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“:

Ergebnisse der Zuschauer-Suche

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 die Links- und Rechtspfeiltasten, um zwischen den Einträgen zu wechseln:

Suchzeitachse

Abbildung 4: Suchzeitachse.