本頁面由 Cloud Translation API 翻譯而成。

使用 Winscope 追蹤視窗轉換

Winscope 是一項網頁工具，可讓使用者在動畫和轉場期間和之後，記錄、重播及分析多個系統服務的狀態。Winscope 會將所有相關的系統服務狀態記錄到追蹤檔案中。藉由使用追蹤檔案使用 Winscope UI，您可以重播、逐步執行和偵錯轉換，藉此檢查每個動畫影格 (無論是否有錄製畫面) 的狀態。

產生可載入至 Winscope 的追蹤記錄的系統服務如下：

SurfaceFlinger
WindowManager
WMShell
輸入法編輯器
發射器

執行 Winscope 追蹤記錄檢視器

Winscope 追蹤功能是平台上服務的一部分。本節概述下載、建構及執行 Winscope 追蹤記錄檢視器所需的步驟。

請按照下列步驟設定電腦，以便執行 Winscope 追蹤程式：

下載 Android 原始碼。
前往 Winscope 資料夾：
```
cd development/tools/winscope
```
使用以下方式安裝依附元件：
```
npm install
```
如要查看可用指令清單，請執行： npm run
使用下列指令建構所有實際工作環境和測試目標：
```
npm run build:prod
```
使用以下方式執行 Winscope：
```
npm run start
```

擷取追蹤記錄

您可以在裝置上、透過 Winscope 或 Android Debug Bridge (ADB) 指令擷取追蹤記錄。

在裝置上擷取追蹤記錄

在裝置上擷取追蹤記錄，以便在提交動畫問題的錯誤時收集資料。由於您無法自訂設定，因此系統會使用這個方法記錄所有 UI 追蹤記錄。

使用 Android 裝置：

啟用開發人員選項。
選取「開發人員選項下的「系統追蹤」。
啟用「收集 Winscope 追蹤記錄」。
在「其他」下方：
1. 啟用「在錯誤報告中附上記錄檔」。
2. 啟用「顯示快速設定方塊」。
前往需要重現錯誤的位置。
如要開始擷取，請開啟「快速設定」，然後選取「錄製追蹤記錄」：

圖 1. 含有「Record Trace」功能的快速設定選單。
僅執行重現錯誤的必要步驟。
如要停止擷取，請開啟「快速設定」並選取「停止追蹤」。
使用列出的其中一個選項共用已擷取的記錄，例如 Gmail、雲端硬碟或 BetterBug。

透過 Winscope 擷取追蹤記錄

您可以使用 Winscope 擷取追蹤記錄，用於本機開發和偵錯。Winscope 使用 ADB，支援透過 USB 或 Wi-Fi 進行裝置連線。

在 Winscope 上：

在「Collect Traces」畫面中，按一下「ADB Proxy」：

圖 2. 在 Winscope 擷取追蹤記錄。
啟動 Winscope ADB Connect 代理程式，即可直接從瀏覽器擷取追蹤記錄。

注意：必須使用 Python 3.5 以上版本和 ADB。

執行下列指令：

python3 $ANDROID_BUILD_TOP/development/tools/winscope/src/adb/winscope_proxy.py

如要開始擷取，請在「Collect Traces」畫面中選取目標與設定，然後按一下「Start trace」：

圖 3. 在 Winscope 上收集追蹤記錄。
如要停止擷取，請按一下「End trace」：

圖 4. 在 Winscope 上結束追蹤記錄。

當工具將追蹤記錄上傳至 Winscope 的 UI 時，畫面上會顯示「Fetching」和「Parsing Proto Files」訊息。

使用 Winscope 產生狀態傾印

如要使用 Winscope 擷取狀態傾印，請在「Collect Traces」畫面中選取「Dump」分頁，然後按一下「Dump state」：

dump-winscope

圖 5. 在 Winscope 上傾印狀態。

使用 ADB 指令擷取追蹤記錄

請先執行 adb root，再針對下列每個追蹤記錄執行 adb shell 指令。追蹤記錄結束時，追蹤檔可在 /data/misc/wmtrace 中找到。如要從裝置複製檔案或目錄及其子目錄，請參閱「將檔案複製到裝置/從裝置複製檔案」。詳情請參閱 adb。

WindowManager 追蹤記錄

如何擷取 WindowManager 追蹤記錄：

啟用追蹤：
```
adb shell wm tracing start
```
停用追蹤記錄：
```
adb shell wm tracing stop
```
在執行追蹤記錄擷取作業時，將記錄資料儲存到檔案：
```
adb shell wm tracing save-for-bugreport
```
每個影格一次記錄追蹤記錄一次：
```
adb shell wm tracing frame
```
記錄每筆交易：
```
adb shell wm tracing transaction
```
設定記錄檔大小上限 (以 KB 為單位)：
```
adb shell wm tracing size
```
列印追蹤記錄狀態：
```
adb shell wm tracing status
```
將記錄層級設為 critical (僅限顯示資訊較少的可見視窗)、trim (所有資訊較少的視窗) 或 all (所有視窗和資訊)：
```
adb shell wm tracing level
```

ProtoLog

下列指令適用於 ProtoLog 系統。

在 system_server 程序中：

啟動 ProtoLog：
```
adb shell cmd window logging start
```
停止 ProtoLog：
```
adb shell cmd window logging stop
```

為特定記錄群組啟用 ProtoLog：

adb shell cmd window logging enable [group...]

為特定記錄群組停用 ProtoLog：

adb shell cmd window logging disable [group...]

為指定的記錄群組啟用 Logcat 記錄功能：

adb shell cmd window logging enable-text [group...]

為指定的記錄群組停用 Logcat 記錄功能：

adb shell cmd window logging disable-text [group...]

在 WMShell 中：

啟動 ProtoLog：

adb shell dumpsys activity service SystemUIService WMShell

轉換追蹤

下列指令用於轉換追蹤：

在 system_server 程序中：

開始追蹤記錄：

adb shell cmd window shell tracing start

停止追蹤記錄：

adb shell cmd window shell tracing stop

在 WMShell 中啟動追蹤記錄：

adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

在 WMShell 中停止追蹤記錄：

adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

輸入法編輯器

以下是輸入法編輯器 (IME) 追蹤的相關指令：

啟動輸入法 (IM) 用戶端、輸入法服務 (IMS) 和輸入法管理服務 (IMMS) 的 IME 追蹤：
```
adb shell ime tracing start
```
開始追蹤 IME 用戶端、IMS 和 IMMS：
```
adb shell ime tracing stop
```

SurfaceFlinger 圖層

SurfaceFlinger 圖層追蹤功能會使用 Perfetto 追蹤記錄進行擷取。如需設定資訊，請參閱 Trace 設定。

請參閱下列 SurfaceFlinger 圖層追蹤設定範例：

unique_session_name: "surfaceflinger_layers_active"
buffers: {
    size_kb: 63488
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.layers"
        surfaceflinger_layers_config: {
            mode: MODE_ACTIVE
            trace_flags: TRACE_FLAG_INPUT
            trace_flags: TRACE_FLAG_COMPOSITION
            trace_flags: TRACE_FLAG_HWC
            trace_flags: TRACE_FLAG_BUFFERS
            trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
        }
    }
}

請參閱下列範例指令，瞭解如何產生 SurfaceFlinger 圖層的追蹤記錄：

adb shell -t perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

SurfaceFlinger 交易

SurfaceFlinger 交易追蹤會使用 Perfetto 追蹤記錄進行擷取。如需設定資訊，請參閱追蹤記錄設定。

請參閱以下 SurfaceFlinger 主動追蹤的 Perfetto 設定範例：

unique_session_name: "surfaceflinger_transactions_active"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_ACTIVE
        }
    }
}
write_into_file: true
file_write_period_ms: 100

請參閱下方 SurfaceFlinger 持續追蹤的 Perfetto 設定範例：

unique_session_name: "surfaceflinger_transactions_continuous"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_CONTINUOUS
        }
    }
}

請參閱下列範例指令，瞭解如何產生 SurfaceFlinger 交易的追蹤記錄：

    adb shell perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

使用 ADB 產生狀態傾印

Winscope 會從錯誤報告讀取 WindowManager 和 SurfaceFlinger 狀態的快照。錯誤報告會將狀態儲存為 proto 資料夾中的個別 proto 檔案。如要使用 ADB 產生狀態傾印，請執行下列指令。

針對 WindowManager：

adb exec-out dumpsys window --proto > window_dump.winscope

SurfaceFlinger：

adb exec-out dumpsys SurfaceFlinger --proto > sf_dump.winscope

分析追蹤記錄

如要對造成動畫問題的暫時性和無效狀態進行偵錯，Winscope 會匯總不同的追蹤檔、針對影格和時間軸提供搜尋和視覺化功能，並以連貫的方式呈現 Protobuf 訊息。在 Winscope 分析追蹤記錄，有助於識別錯誤發生的確切層、框架和狀態。

使用 Winscope

擷取追蹤記錄後，請分析 Winscope 的追蹤記錄：

使用右側面板上傳已儲存的追蹤記錄。您可以移除已上傳的追蹤記錄，或上傳更多追蹤記錄。

注意：支援的追蹤記錄檔案類型包括 Winscope 追蹤記錄、含有 Winscope 中繼資料的 MP4 影片 (使用 ADB 收集)、ZIP 檔案和錯誤報告。

圖 6. 在 Winscope 上傳追蹤記錄。
按一下「查看追蹤記錄」，以視覺化方式呈現上傳的追蹤記錄。每個追蹤記錄的分頁會顯示在視窗的頂端面板上。如果上傳的檔案包含相關追蹤記錄，畫面錄製追蹤記錄的浮動檢視畫面會重疊在畫面上。

圖 7. 在 Winscope 中查看追蹤記錄。

請使用視窗頂端面板中的 UI 重新命名，並下載您上傳的追蹤記錄或上傳新的追蹤記錄。
使用視窗底部面板中的時間滑桿工具，瀏覽一段時間內的追蹤記錄。如需其他時間導覽功能，請使用下列功能，如圖 8 所示：
- 如要前往特定時間或出現次數，請使用時間顯示方塊 (左下角) 中的遊標 (時間滑桿)、左側和右側箭頭，或是鍵盤上的左右箭頭。
- 如要在時間軸上顯示所選以不同顏色標示的追蹤記錄，請使用時間滑桿左側的下拉式選單。根據預設，系統會在時間軸上顯示使用追蹤分頁檢視的最後三個追蹤記錄。
- 如要查看所有已上傳追蹤記錄的詳細資料，請使用放大或縮小工具 (位於時間滑桿下方)，或使用鍵盤捲動。使用重設按鈕重設縮放比例。
- 如要查看特定期間的追蹤記錄分佈情形，請按一下向上箭頭 (右下角)。
圖 8. Winscope 上的時間導覽。

在展開的檢視畫面 (圖 9) 中，選取並放大特定時間範圍，以便進一步檢查：

圖 9.Winscope 的展開式時間軸。
如要檢查追蹤記錄，您可以透過螢幕錄製來查看裝置狀態。如要檢查特定追蹤記錄，請按一下工具頂端面板中的相關追蹤記錄分頁。
- 針對 Surface Flinger 追蹤記錄，三個面板會顯示特定時間範圍內的追蹤記錄檢視畫面，如圖 10 所示：
  
  圖 10. Winscope 上的 Surface Flinger 追蹤記錄。
  - 圖層檢視畫面：矩形疊加層中的圖層 3D 檢視畫面。下列 UI 元素會依照位置、大小、轉換和 z-order 調整矩形，讓圖形元素算繪出來：
    - 「旋轉」滑桿 (在「圖層」檢視畫面的左上方) 會旋轉圖層矩形，以所選角度查看。
    - 「Spacing」滑桿 (位於「圖層」檢視畫面的右上方) 會調整圖層之間的間距，以建立所選的複合檢視畫面。
    - 縮放工具 (在「圖層」檢視畫面的右上方) 會放大，並將縮小為圖層，以便進行檢查。
    - 重設按鈕 (「圖層」檢視畫面的右上方) 會將相機設定還原為原始檢視畫面。
    - 拖曳矩形即可提升縮放大小。
    注意： 「僅限可見」和「顯示虛擬」核取方塊已淘汰。
  - 「Hierarchy」(階層) 檢視畫面：整個圖層的階層。
    - 選取「Only visible」(階層檢視畫面的右上方) 後，系統會隱藏階層中的隱藏層，以利於在畫面上顯示元素。
    - 選取「Flat」(階層) (在階層檢視的右上方) 時，系統會以平面化的圖層清單顯示階層。
    - 只有在有狀態轉換時，系統才會選取「顯示差異」 (階層檢視畫面的左上方)。如果選取，此工具會比較目前狀態與先前狀態。新的元素會以綠色醒目顯示，已刪除的元素會以紅色醒目顯示，修改過的元素則會以藍色醒目顯示。
  - 「Properties」檢視畫面：所選圖層的屬性。「Properties」檢視畫面的頂端面板只會顯示關鍵屬性資訊，例如「Visibility」、「Geometry」和「Buffer」。「Properties」檢視畫面的底部面板包含了所有屬性的 Proto Dump。
    - 「Show Diff」核取方塊 (屬性檢視畫面的左上方) 的運作方式與「Hierarchy」檢視畫面相同。
    - 選取「顯示預設值」 (屬性檢視畫面的左上方)，即可在 Proto Dmp 上顯示預設的 proto 值。根據預設，這些值不會列在 Proto 傾印中。預設的 proto 值會取自 proto 欄位定義。如果 proto 欄位沒有設定非空值的預設值，則顯示的預設 proto 值如下：
      - 字串：空值
      - 數字：0
      - 布林值：False
      - 物件：空值
  在三個檢視畫面和螢幕錄製選項之間選取項目會同步處理，亦即在您導覽至不同的時間點時，所有追蹤記錄都會同步更新。如要查看圖層的屬性，請在階層檢視畫面中按一下圖層，或是在「屬性」檢視畫面中按一下相應的矩形。紫色矩形表示檢視追蹤記錄已附加至這個圖層。按兩下紫色圖層時，UI 會前往相關檢視區塊追蹤記錄分頁。
- 對於視窗管理員追蹤記錄，三個面板會顯示特定時間範圍內的追蹤記錄檢視畫面，如圖 11 所示：
  - Windows 檢視畫面：圖層的 3D 檢視畫面。
  - 「階層」檢視畫面：圖層的完整階層。
  - 「Properties」檢視畫麵包含所有屬性的 Proto Dump。
  三個檢視畫面和螢幕錄製畫面之間的選取內容會同步，也就是說，當您瀏覽至不同的時間點時，所有追蹤記錄都會同步更新。
  
  注意： 三個檢視畫面上 UI 元素的函式和位置與 Surface Flinger 追蹤記錄中的函式和位置相似。
  
  圖 11. Winscope 上的視窗管理員追蹤記錄。
- 對於「交易」追蹤記錄，Surface Flinger 和 Window Manager 之間的交易會以表格格式呈現，可透過顯示的 ID、類型和文字進行搜尋，並搭配顯示原型轉儲的屬性檢視畫面。兩個檢視畫面與螢幕錄製項目之間的選取項目會保持同步：
  
  圖 12. Winscope 上的交易追蹤記錄。
- 對於 ProtoLog 追蹤記錄，系統會以表格格式呈現資訊，並可透過標記、來源檔案和文字進行搜尋：
  
  圖 13. Winscope 的 ProtoLog 追蹤記錄。
- 如果是「Transitions」追蹤記錄，則會顯示包含 ID、類型、傳送時間、持續時間和狀態的轉換作業清單，以及所選轉換的屬性：
  
  圖 14. Winscope 上的轉場追蹤記錄。