追蹤記錄搜尋

使用 SQL 找出 Winscope Perfetto 追蹤記錄中的特定狀態。在 Winscope UI 中使用全域「Search」(搜尋) 檢視器執行查詢,並以表格形式呈現結果:

搜尋檢視者分頁

圖 1. 「搜尋檢視器」分頁。

您可以在「搜尋」檢視器中,對 Perfetto 追蹤記錄編寫及執行自訂 SQL 查詢,並存取最近和已儲存的查詢。Winscope 提供專用的 SQL 檢視畫面,協助搜尋 SurfaceFlinger、交易、轉場效果和 ViewCapture 追蹤記錄。

所有檢視畫面都應遵循下列慣例:

  • property」和「flat_property」欄:

    • 屬性名稱採用蛇形命名法,例如 LayerProto 中的 visible_region
    • 點記號表示巢狀屬性,例如 visible_region.rect

    • property 中的重複欄位會以方括號區分:

      舉例來說,在重複欄位 visible_region.rect 的兩個執行個體中,top 欄位會以 visible_region.rect[0].topvisible_region.rect[1].top 表示。

    • flat_property 中的重複欄位無法區分:

      舉例來說,在重複欄位 visible_region.rect 的兩個執行個體中,top 欄位在兩個執行個體中都以 visible_region.rect.top 表示。

  • valueprevious_value 欄中,布林值會以 0 (False) 或 1 (True) 表示。

Winscope 會將追蹤專用資料表的資料與 Perfetto args 資料表的資料彙整,藉此建立這些檢視畫面。您可以直接查詢這些資料表。在 args 資料表中,keyflat_keydisplay_value 資料欄分別對應至檢視畫面資料欄 propertyflat_propertyvalue

args 個資料表:

Column 說明
arg_set_id 用於關聯一組引數
flat_key 來自 proto 訊息的屬性名稱,不計入重複欄位
key 來自 proto 訊息的屬性名稱,會將重複欄位納入考量
value_type 屬性值類型
int_value 如果值類型為整數,則為屬性值
string_value 如果值類型為字串,則為屬性值
real_value 如果值類型為實數,則為屬性值
display_value 屬性值轉換為字串

SurfaceFlinger SQL 檢視區塊

SurfaceFlinger Proto 資料採用下列格式:

如要搜尋圖層資料,請使用 sf_layer_search 檢視畫面。這個檢視畫面包含下列資料欄:

Column 說明
state_id 圖層所屬項目的列 ID
ts 圖層所屬項目的時間戳記
layer_id 圖層 ID
parent_id 父項的圖層 ID
layer_name 圖層名稱
property 考量重複欄位的屬性名稱
flat_property 屬性名稱考量重複欄位
value 字串格式的屬性值
previous_value 字串格式的屬性值,來自前一個項目

如要搜尋階層根資料,請使用 sf_hierarchy_root_search 檢視畫面。這個檢視畫面包含下列資料欄:

Column 說明
state_id 項目的列 ID
ts 項目時間戳記
property 考量重複欄位的屬性名稱
flat_property 屬性名稱考量重複欄位
value 字串格式的屬性值
previous_value 字串格式的先前項目屬性值

查詢範例

  • 找出 IME 層具有有效螢幕界限的所有影格:

    SELECT ts, value, previous_value FROM sf_layer_search
      WHERE layer_name like 'IME%'
      AND property='screen_bounds.bottom'
      AND value<='24000'
    
  • 找出 Taskbar 圖層 color.a (Alpha) 發生變化的所有影格:

    SELECT ts, value, previous_value FROM sf_layer_search
      WHERE layer_name like 'Taskbar%'
      AND property='color.a'
      AND value!=previous_value
    
  • 找出所有 Wallpaper 底端界線小於或等於 2400 的影格:

    SELECT ts, value, previous_value FROM sf_layer_search
      WHERE layer_name LIKE 'Wallpaper%'
      AND property='bounds.bottom'
      AND cast_int!(value) <= 2400
    
  • 列出具有有效圖層堆疊的螢幕的所有屬性:

    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, ']')
        ),
        '%'
      )
    
  • 找出所有顯示向後滑動手勢的影格

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

資料表

SurfaceFlinger 檢視區塊是使用下列基礎資料表建立。

surfaceflinger_layers_snapshot

Column 說明
id 項目的資料列 ID
ts 項目時間戳記
arg_set_id 用於將 args 資料表中的資料列與這個項目建立關聯的 ID

surfaceflinger_layer

Column 說明
id 圖層的資料列 ID
snapshot_id 圖層所屬「surfaceflinger_layers_snapshot」項目的資料列 ID
arg_set_id 用於將 args 資料表中的資料列與這個圖層建立關聯的 ID

交易 SQL 檢視畫面

交易 Proto 資料採用 TransactionTraceEntry 格式。

如要搜尋交易記錄追蹤資料,請使用 transactions_search 檢視畫面。這個檢視畫面包含下列資料欄:

Column 說明
state_id Proto 屬性所屬項目的列 ID
ts Proto 屬性所屬項目的時間戳記
transaction_id 交易 ID (如有)
property 考量重複欄位的屬性名稱
flat_property 屬性名稱考量重複欄位
value 字串格式的屬性值

查詢範例

  • 找出套用交易的影格,將圖層 x 位置變更為 -54.0:

    SELECT ts, transaction_id, value FROM transactions_search
      WHERE flat_property='transactions.layer_changes.x'
      AND value='-54.0'
    
  • 找出新增 ImeContainer 圖層的影格:

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

資料表

「Transactions」SQL 檢視區塊是使用下列基礎資料表建立。

surfaceflinger_transactions

Column 說明
id 項目的資料列 ID
ts 項目時間戳記
arg_set_id 用於將 args 資料表中的資料列與這個項目建立關聯的 ID
vsync_id 與這個項目中所有交易相關聯的 VSync ID

android_surfaceflinger_transaction

Column 說明
id 交易的列 ID
snapshot_id 交易所屬「surfaceflinger_transactions」項目的列 ID
arg_set_id 用於將 args 資料表中的資料列與這項交易建立關聯的 ID
transaction_id 從 proto 訊息取得的交易 ID
pid 從 Proto 訊息取得的交易 PID
uid 從 proto 訊息取得的交易 UID
layer_id 與交易相關聯的圖層 ID (如有)
display_id 與交易相關聯的螢幕 ID (如有)
flags_id 用於從 android_surfaceflinger_transaction_flag 擷取相關聯旗標的 ID
transaction_type 交易類型

android_surfaceflinger_transaction_flag

Column 說明
flags_id 對應 android_surfaceflinger_transaction 中資料列的值
flag 翻譯後的旗標字串

系統會根據交易類型,從不同 proto 訊息格式將個別交易新增至 args 表格:

  • LAYER_ADDEDLayerCreationArgs 格式
  • LAYER_CHANGEDLayerState 格式
  • DISPLAY_ADDEDDisplayState 格式
  • DISPLAY_CHANGEDDisplayState 格式
  • LAYER_DESTROYED:沒有引數
  • LAYER_HANDLE_DESTROYED:沒有引數
  • DISPLAY_REMOVED:沒有引數
  • NOOP:沒有引數

轉換 SQL 檢視區塊

轉換 proto 資料採用 ShellTransition 格式。

如要搜尋轉場效果資料,請使用 transitions_search 檢視畫面。這個檢視畫面包含下列資料欄:

Column 說明
ts 傳送時間;如果有的話,會改為傳送時間,否則為 0
transition_id 取自 Proto 訊息的轉移 ID
property 考量重複欄位的屬性名稱
flat_property 屬性名稱考量重複欄位
value 從 proto 訊息取得的交易 UID

查詢範例

找出 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

資料表

系統會使用下列基礎資料表建立「轉換」檢視畫面。

window_manager_shell_transitions

Column 說明
id 轉移作業的列 ID
ts 傳送時間;如果有的話,會改為傳送時間,否則為 0
transition_id 取自 Proto 訊息的轉移 ID
arg_set_id 用於將 args 資料表中的資料列與這項轉換建立關聯的 ID
transition_type 從 proto 訊息取得的轉場效果類型
send_time_ns 從 Proto 訊息取得轉場效果傳送時間
dispatch_time_ns 從 Proto 訊息取得的轉移調度時間
duration_ns 如有開始和結束時間,則為轉場效果的持續時間
handler 轉換處理常式:從 window_manager_shell_transition_handlers 擷取翻譯內容
status 轉移狀態:playedmergedaborted
flags 從 Proto 訊息取得的轉場效果旗標

window_manager_shell_transition_handlers

Column 說明
handler_id 對應 window_manager_shell_transitions 中「handler」欄值的 ID
handler_name 字串翻譯

android_window_manager_shell_transition_participants

Column 說明
transition_id 取自原始 Proto 訊息的轉移 ID
layer_id SurfaceFlinger 圖層參與者 ID
window_id WindowManager 容器參與者的 ID

查看 ViewCapture SQL 檢視區塊

ViewCapture proto 資料採用 View 格式。

如要搜尋 ViewCapture 資料,請使用 viewcapture_search 檢視畫面。這個檢視畫面包含下列資料欄:

Column 說明
state_id 檢視畫面所屬狀態的列 ID
ts 檢視畫面所屬狀態的時間戳記
package_name 套件名稱
window_name 視窗名稱
class_name 查看課程名稱
property 考量重複欄位的屬性名稱
flat_property 屬性名稱考量重複欄位
value 字串格式的屬性值
previous_value 前一個狀態的屬性值 (字串格式)

查詢範例

SearchContainerView 沿 y 軸移動時,找出所有狀態:

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

資料表

ViewCapture 檢視區塊是使用下列基礎資料表建立。

android_viewcapture

Column 說明
id 項目的資料列 ID
ts 項目時間戳記
arg_set_id 用於將 args 資料表中的資料列與這個項目建立關聯的 ID

android_viewcapture_view

Column 說明
id 檢視畫面的列 ID
snapshot_id 檢視畫面所屬的「android_viewcapture」項目列 ID
arg_set_id 用於將 args 資料表中的資料列與這個檢視畫面建立關聯的 ID

ProtoLog SQL 資料表

ProtoLog proto 資料採用 ProtoLogMessage 格式。這個檢視畫面包含下列資料欄:

Column 說明
ts 記錄的時間戳記
level 記錄層級
tag 記錄群組標記
message 記錄訊息
stacktrace 堆疊追蹤 (如有)
location 訊息的來源程式碼位置

查詢範例

  • 找出訊息包含 transition 的所有記錄:

    SELECT ts, message, location FROM protolog
      WHERE message LIKE '%transition%'
    
  • 找出包含有效交易 ID 的所有記錄:

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

執行查詢

您可以使用「搜尋」檢視器左側的「全域搜尋」面板執行搜尋查詢。

首次與「GLOBAL SEARCH」(全域搜尋)面板互動時,追蹤搜尋會初始化,Winscope 則會建立輔助 SQL 檢視區塊。這項作業需要幾秒鐘才能完成。 在追蹤搜尋初始化期間,時間軸無法使用。

如要開始查詢,請在搜尋框中輸入查詢內容,然後按一下「執行搜尋查詢」或按下鍵盤上的 Enter 鍵來執行查詢。

完成後,結果表格會顯示在中間面板。查詢會顯示在搜尋框下方,並提供欄位,方便您在工作階段之間儲存查詢。

如要存取已儲存的查詢,請按一下左側面板中的「已儲存」分頁;如要存取最近執行的查詢,請按一下「最近」分頁:

搜尋檢視器左側面板

圖 2. 搜尋檢視器左側面板。

結果

所有查詢都會傳回表格形式的結果,並顯示在可捲動的檢視畫面中,互動方式與以記錄為基礎的追蹤檢視器 (例如「交易」和「ProtoLog」) 類似:

搜尋觀眾結果

圖 3. 搜尋觀眾結果。

如果產生的資料表包含 ts 資料欄,系統會將該資料欄中的值解讀為時間戳記,並以新資料列的形式新增至時間軸疊加層。按一下這個資料列,然後使用向左鍵和向右鍵在項目之間切換:

搜尋時間軸

圖 4. 搜尋時間軸。