Trace search

Use SQL to find specific states in Winscope Perfetto traces. Use the global Search viewer in the Winscope UI to run queries and visualize tabulated results:

Figure 1. Search viewer tab.

The Search viewer lets you write and run custom SQL queries on Perfetto traces, as well as access recent and saved queries. Winscope provides specialized SQL views to aid with searching SurfaceFlinger, Transactions, Transitions, and ViewCapture traces.

Use the following conventions for all views:

• For property and flat_property columns:

  • Property names are in snake case, for example visible_region from LayerProto.

  • A dot notation represents nested properties, for example, visible_region.rect.

  • Repeated fields in property are distinguished with square brackets:

    For example, within two instances of repeated field visible_region.rect, the top field is represented by visible_region.rect[0].top and visible_region.rect[1].top.

  • Repeated fields in flat_property are indistinguishable:

    For example, within two instances of repeated field visible_region.rect, the top field is represented by visible_region.rect.top in both the instances.

• For value and previous_value columns, boolean values are represented by 0 (False) or 1 (True).

Winscope creates these views by joining data from trace-specific tables with the Perfetto args table. You can query these tables directly. In the args table, the key, flat_key, and display_value columns are analogous to view columns property, flat_property, and value respectively.

args table:

SurfaceFlinger SQL views

SurfaceFlinger proto data uses these formats:

• The layer data is in the LayerProto format.

• The hierarchy root data is in the LayersSnapshotProto format.

To search layer data, use the sf_layer_search view. This view includes these columns:

To search hierarchy root data, use the sf_hierarchy_root_search view. This view includes these columns:

Example queries

• Find all frames where the IME layer has valid screen bounds:

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

• Find all frames where the Taskbar layer color.a (alpha) changes:

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

• Find all frames where the Wallpaper bottom bound is less than or equal to 2400:

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

• List all properties for displays with a valid layer stack:

  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, ']')
      ),
      '%'
    )
  

Data tables

The SurfaceFlinger views are created using the following underlying tables.

surfaceflinger_layers_snapshot:

surfaceflinger_layer:

Transactions SQL view

The transactions proto data uses the TransactionTraceEntry format.

To search Transactions trace data, use the transactions_search view. This view includes these columns:

Example queries

• Find the frame where a transaction was applied to change layer x position to -54.0:

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

• Find the frame where the ImeContainer layer was added:

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

Data tables

The Transactions SQL view is created using the following underlying tables.

surfaceflinger_transactions:

android_surfaceflinger_transaction:

android_surfaceflinger_transaction_flag:

Individual transactions are added to the args table from different proto message formats based on their transaction type:

• LAYER_ADDED: LayerCreationArgs format
• LAYER_CHANGED: LayerState format
• DISPLAY_ADDED: DisplayState format
• DISPLAY_CHANGED: DisplayState format
• LAYER_DESTROYED: No args
• LAYER_HANDLE_DESTROYED: No args
• DISPLAY_REMOVED: No args
• NOOP: No args

Transitions SQL view

The transitions proto data uses the ShellTransition format.

To search Transitions data, use the transitions_search view. This view includes these columns:

Example queries

Find properties of transitions handled by the DefaultMixedHandler:

  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

Data tables

The Transitions view is created using the following underlying tables.

window_manager_shell_transitions:

window_manager_shell_transition_handlers:

android_window_manager_shell_transition_participants:

ViewCapture SQL view

The ViewCapture proto data uses the View format.

To search ViewCapture data, use the viewcapture_search view. This view includes these columns:

Example queries

Find all states when SearchContainerView moved in the y-direction:

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

Data tables

The ViewCapture view is created using the following underlying tables.

android_viewcapture:

android_viewcapture_view:

ProtoLog SQL table

The ProtoLog proto data uses the ProtoLogMessage format. This view includes these columns:

Example queries

• Find all logs with a message containing transition:

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

• Find all logs that contain valid transaction IDs:

  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, '%');
  

Run queries

You can run search queries using the GLOBAL SEARCH panel on the left of the Search viewer.

When you first interact with the GLOBAL SEARCH panel, trace search initializes and Winscope creates the helper SQL views. This takes a few seconds. While trace search is initializing, the timeline isn't available.

To start a query, write a query in the search box and click Run Search Query or press Enter on your keyboard to run it.

When finished, the table of results shows in the middle panel. Your query appears below the search box, with a field to save the query between sessions.

You can access saved queries by clicking the Saved tab in the left panel, and access recently run queries by clicking the Recent tab:

Figure 2. Search viewer left panel.

Results

All queries return tabulated results, shown in a scrollable view with interactive behavior similar to the log-based trace viewers, such as Transactions and ProtoLog:

Figure 3. Search viewer results.

If the resulting table contains a ts column, the values in that column are interpreted as timestamps and added to the timeline overlay as a new row of entries. Click this row and use your left and right arrow keys to navigate between entries:

Figure 4. Search timeline.