ffx log 是 ffx 內建的記錄檢視公用程式。本指南說明如何設定及使用 ffx log 查看 Fuchsia 裝置上的記錄。
如要啟動記錄檢視器，請執行下列指令：
ffx log
這個指令會列印目前的記錄項目，並讓連線開啟以串流新的記錄項目。如要列印記錄目前的內容並結束，請使用 dump：
ffx log dump
主動記錄
執行 ffx 指令後，ffx Daemon 會在背景中保持運作。Daemon 會主動探索 Fuchsia 裝置，並在可以連線時將其連線。
透過主動記錄，ffx Daemon 會在連線後立即在背景從目標裝置讀取記錄。系統會在主體機器上快取記錄檔，但有一定的空間限制。
達到空間限制時，系統會將記錄「輪替」：最舊的記錄會刪除，以騰出空間存放最新的記錄。
這表示當您使用 ffx log 查看記錄時，實際上是從主體機器的快取讀取記錄，而不是直接從目標裝置讀取。一般而言，除非裝置產生極大量記錄量，但在極少數情況下，這項做法不應對記錄檢視器造成任何明顯的延遲。
功能
由於記錄檔會在主體機器上快取，因此您可以查看從裝置先前啟動的目標裝置快取過的記錄。舉例來說，如果裝置當機，您可以檢視當機之前的記錄 (如果已及時快取記錄)。
您可以使用 ffx log dump 查看上一個工作階段的記錄。例如，查看裝置之前啟動的記錄：
ffx --target <NODENAME> log dump ~1
~1 可識別相對於您要查看的最新工作階段，其中 0 會保留給該目標裝置目前作用中的工作階段 (無論是否存在使用中的工作階段)。您可以使用 ~2、~3 等項目查看先前的啟動項目。
設定
以下是與主動式記錄檔快取相關的 3 種設定：
proactive_log.max_sessions_per_target：要在主機上保留快取的啟動工作階段數量上限。預設值為 5 (也就是說，重新啟動 6 後，最早啟動工作階段的記錄會刪除)。proactive_log.max_session_size_bytes：每個工作階段要快取的位元組數上限。預設值為 100 MB (也就是說，在磁碟上有 100 MB 的記錄後，系統會刪除該工作階段中最舊的記錄檔區塊)proactive_log.max_log_size_bytes：單一記錄檔區塊要使用的位元組數上限。一般來說，您不需要變更這項設定。預設值為 1 MB。
象徵
系統會於從裝置讀取記錄時 (在寫入主機記錄快取之前)，在背景將記錄符號化。不過，這項背景處理作業代表 symbolizer 主機工具中的設定錯誤或符號索引設定錯誤，可能會導致記錄未經符號化，而不會顯示任何可見的警告。設定 symbolizer 工具時發生的錯誤會記錄在 ffx Daemon 記錄檔中。
採用 Fuchsia 來源結帳設定的使用者不需要執行任何額外設定；符號化功能會自動執行，就像 fx log 一樣。如果使用者未採用 Fuchsia 來源結帳設定，就必須設定適合其開發環境的符號索引。
ffx log 指令會嘗試偵測 symbolizer 工具中的常見錯誤設定，但無法偵測所有設定。如果系統並未將記錄符號化，請回報錯誤。
設定符號化工具
與符號化相關的兩個設定參數如下：
proactive_log.symbolize.enabled：切換是否嘗試符號化。預設值為true。proactive_log.symbolize.extra_args：直接傳遞至symbolizer主機工具的額外參數原始字串。這可用於設定遠端符號伺服器等。預設值為""。
篩選記錄檔
ffx log 指令提供其他選項，可讓您篩選從目標裝置擷取的記錄。您可以根據時間戳記、元件、標記或記錄層級，將篩選器套用至記錄。
ffx log --filter hello-world --severity error
如需篩選選項的完整清單，請參閱參考說明文件。
記錄垃圾內容篩選器
您可以從 ffx log 指令的輸出內容中篩選垃圾項目。如要篩選記錄，您可以在 log_cmd.spam_filepath 鍵下的 ffx 設定或 ffx log 指令 --spam-list-path /path/to/spam/file.json 的標記中定義垃圾內容定義檔案的路徑。詳情請參閱參考說明文件。
這可讓您定義自己的垃圾郵件定義，篩選在開發過程中可能覺得不實用的記錄。
JSON 結構定義
垃圾記錄定義檔案會以 JSON 格式儲存。本節說明用來將資料序列化的 JSON 結構定義。
| 鍵 | 值類型 | 說明 |
|---|---|---|
| 垃圾記錄 | LogspamEntry 清單 | 垃圾內容記錄項目清單 |
以下範例代表空白的垃圾記錄檔定義：
{
"logSpam": []
}
LogspamEntry
| 鍵 | 值類型 | 說明 |
|---|---|---|
| 檔案 (選填) | 字串 | 垃圾內容記錄的來源檔案路徑 |
| 一行 (選填) | 數字 (64 位元) | 垃圾內容記錄的來源行數 |
| payloadRegex (選用) | 字串 | 與垃圾內容記錄內容相符的 Rust Regex 字串 |
以下範例代表 LogSpamEntry 範例：
{
"file": "path/to/log_source.cc",
"line": 95,
"payloadRegex": "Disconnected\\.*",
}
發生以下任何情況時，LogSpamEntry 都會視為有效 (忽略其他組合)
| 「file」 | 「線」 | 「payloadRegex」 | 行為 |
|---|---|---|---|
| ✓ | ✓ | ✓ | 如果記錄的來源與「file」和「line」相符，且內容與「payloadRegex」相符，系統就會將記錄識別為垃圾內容 |
| ✓ | ✓ | ✗ | 如果記錄的來源符合「file」和「行」，可將記錄識別為垃圾內容 |
| ✗ | ✗ | ✓ | 如果記錄沒有來源資訊，且內容符合「payloadRegex」 |
記錄設定
記錄篩選器會修改 ffx log 顯示記錄的方式，但不會影響目標裝置上元件發出的記錄項目。使用 --select 選項傳送要求，以在記錄工作階段期間調整特定元件的記錄設定。這項操作會針對與記錄記錄所提供元件選取器相符的任何元件調整記錄層級。
ffx log --select component-selector#log-level
您可以使用此方法暫時啟用低於元件設定的最小嚴重性等級的記錄 (例如 DEBUG 或 TRACE 記錄)，或隱藏元件的雜訊記錄以提升效能。
以下範例會啟用 core/audio 元件的偵錯記錄，並隱藏所有記錄訊息，但網路元件的錯誤除外：
$ ffx log --select core/audio#DEBUG --select core/network/**#ERROR