本文說明用於收集、儲存及傳輸 Fuchsia 追蹤記錄的二進位格式。您可以透過這份文件，搜尋 Fuchsia 追蹤記錄格式中每個欄位的詳細資訊。
總覽
追蹤作業執行期間，追蹤供應器會使用本文件所述的二進位格式，將記錄寫入追蹤緩衝區 VMO，並與追蹤管理員共用。
二進位格式的設計宗旨，是在寫入追蹤記錄時，盡量減少對追蹤主體效能的影響。記錄也會依序寫入，因此如果追蹤作業終止 (正常或異常)，追蹤管理員仍可讀取最後一個格式正確的記錄，從追蹤緩衝區復原已儲存的部分追蹤資料。
隨著追蹤作業進行，追蹤管理工具會匯總參與追蹤記錄收集作業的所有追蹤記錄提供者記錄，並將這些記錄與一些特殊中繼資料記錄串連在一起，形成追蹤記錄封存。
追蹤完成後，trace 指令列程式等工具可以讀取追蹤記錄檔中的追蹤記錄，將結果視覺化或儲存至檔案，以供日後使用。您也可以使用 Perfetto UI，以視覺化方式呈現追蹤記錄封存檔。
功能
- 體積小巧
- 追蹤記錄會將資訊壓縮成少量位元，因此非常精簡。
- 彙整字串、程序和執行緒，進一步壓縮追蹤資料。
- 記憶體對齊
- 追蹤記錄會在記憶體中維持 8 位元組對齊，方便直接寫入記憶體對應的 VMO。
- 大小可變的記錄
- 記錄總大小上限為 32 KB。
- 大型物件可能需要分成多筆記錄。
- 可擴充
- 您可以視需要定義新的記錄類型。
- 系統可以略過無法辨識或格式錯誤的追蹤記錄。
編碼基元
Fuchsia 追蹤格式具有下列編碼基元：
原子
每筆記錄都是以原子序列的形式建構。
每個原子都是以 8 位元組對齊方式寫入，大小也是 8 位元組的倍數，以保留對齊方式。
原子分為兩種：
- 字：64 位元值，可進一步細分為位元欄位。 字詞會以機器字詞順序儲存 (目前支援的所有架構皆為小端序)。
- 串流：以零填補的位元組序列，直到下一個 8 位元組邊界為止。串流會以位元組順序儲存。長度為 8 個位元組確切倍數的串流不會經過填補 (沒有零終止符)。
「欄位」是 64 位元「字詞」的細分，以 [<least significant bit> .. <most significant bit>] 表示，其中包含第一個和最後一個位元位置。所有未使用的位元都保留供日後使用，且必須設為 0。
除非記錄格式另有指定，否則「字詞」和「欄位」會儲存不帶正負號的整數。
串流可儲存 UTF-8 字串或二進位資料，具體取決於記錄格式。
記錄
追蹤記錄是經過二進位編碼的追蹤資訊，由一連串的「原子」組成。
所有記錄都包含標頭字詞，其中含有下列基本資訊：
- 記錄類型：4 位元欄位，用於識別記錄類型和所含資訊。請參閱「記錄類型」。
- 記錄大小：通常為 12 位元欄位，表示記錄中的字數 (8 位元組單位的倍數)，包括記錄標頭本身。記錄檔大小上限為 4095 個字 (32760 個位元組)。非常簡單的記錄可能只有 1 個字 (8 個位元組) 長。 大型記錄使用 32 位元大小欄位，因此最大大小較高。
記錄長度一律為 8 個位元組的倍數，且會以 8 個位元組對齊方式儲存。
封存
追蹤記錄檔是一連串的追蹤記錄，以端對端的方式串連，其中儲存追蹤供應商在追蹤執行期間收集的資訊，以及中繼資料記錄，用於識別及劃分各追蹤供應商產生的追蹤記錄區段。
追蹤記錄封存檔應依序讀取，因為追蹤記錄中較早出現的記錄，可能會影響對追蹤記錄中較晚出現記錄的解讀。會影響封存檔中後續記錄的記錄範例包括字串參照和執行緒參照。
系統不保證事件記錄會依時間戳記排序。部分記錄類型 (例如流程事件) 需要依時間戳記順序處理事件，因此處理追蹤資料的程式應先依時間戳記排序事件，再進行處理。
追蹤系統提供多種工具，可從追蹤封存檔中擷取資訊，並轉換成其他形式以供視覺化。
時間戳記
時間戳記是以衍生自硬體計數器的 64 位元刻度表示。 追蹤初始化記錄會說明每秒的即時節拍數。
根據預設，我們會假設 1 個刻度等於 1 奈秒。
字串參照
字串會編碼為「字串參照」，這是以下列形式表示的 16 位元值：
- 空字串：值為零。
- 已編列索引的字串：最高有效位元為零。較低的 15 位元表示字串表中的索引，先前是使用 String 記錄指派。
- 內嵌字串：最高有效位元為 1。低位 15 位元表示字串長度 (以位元組為單位)。字串內容會顯示在記錄的另一個部分，如記錄格式所指定。
如要讓追蹤記錄更精簡，應使用字串記錄將經常參照的字串 (例如事件類別和名稱常數) 註冊到字串表中，然後依索引參照。
字串表最多可有 32767 個字串。如果達到這個限制，可以替換現有項目或內嵌編碼字串，藉此編碼其他字串。
字串內容本身會儲存為 UTF-8 串流，且不會終止。
字串的理論長度上限為 32767 個位元組，但實際上，由於儲存含有字串的其餘記錄需要空間，因此這個上限會進一步縮減，所以我們保守地將字串長度上限設為 32000 個位元組。
討論串參照
執行緒和程序核心物件 ID (koid) 會編碼為執行緒參照，這是以下列形式表示的 8 位元值：
- 內嵌討論串：值為零。執行緒和程序 koid 會顯示在記錄的其他部分，如記錄格式所指定。
- 已編列索引的執行緒：值不為零。這個值表示執行緒資料表中的索引，先前是使用執行緒記錄指派。
如要讓追蹤記錄更精簡，應使用執行緒記錄將經常參照的執行緒登錄至執行緒表格，然後依索引參照。
字串表格最多可有 255 個執行緒。如果達到這個限制，可以替換現有項目或內嵌編碼執行緒，藉此編碼額外執行緒。
使用者空間物件資訊
追蹤記錄可以包含使用者空間物件的註解 (任何可使用指標類值參照的項目，例如 C++ 或 Dart 物件)，形式為使用者空間物件記錄。追蹤記錄供應商通常會在建立物件時產生這類記錄。
之後，凡是參照相同指標的指標引數，都會與參照對象的註解建立關聯。
這樣一來，您就能輕鬆將人類可解讀的標籤和其他資訊，與稍後出現在追蹤記錄中的物件建立關聯。
核心物件資訊
追蹤記錄可包含有關核心物件的註解 (任何可使用 Zircon koid 參照的項目，例如程序、管道或事件)，形式為核心物件記錄。物件建立時，追蹤記錄供應商通常會產生這類記錄。
之後，凡是參照相同 koid 的核心物件 ID 引數，都會與參照物件的註解建立關聯。
這樣一來，您就能輕鬆將人類可解讀的標籤和其他資訊，與稍後出現在追蹤記錄中的物件建立關聯。
具體來說，追蹤系統就是透過這種方式，將名稱與程序和執行緒的 koid 建立關聯。
引數
引數是鍵/值組合。
許多記錄類型最多可附加 15 個引數，提供開發人員的額外資訊。
引數會加上大小前置字元，就像一般記錄一樣，因此可以略過無法辨識的引數型別。
詳情請參閱「引數類型」。
延長格式
您可以透過下列方式擴充追蹤記錄格式：
- 定義新的記錄類型。
- 在現有記錄類型的保留欄位中儲存新資訊。
- 在現有記錄類型中附加新資訊 (檢查記錄大小和酬載即可偵測到這項資訊)。
- 定義新的引數型別。
記錄類型
記錄類型如下：
- 記錄標頭
- 大型記錄標頭
- 中繼資料記錄 (記錄類型 = 0)
- 初始化記錄 (記錄類型 = 1)
- 字串記錄 (記錄類型 = 2)
- 對話群組記錄 (記錄類型 = 3)
- 事件記錄 (記錄類型 = 4)
- Blob 記錄 (記錄類型 = 5)
- 使用者空間物件記錄 (記錄類型 = 6)
- 核心物件記錄 (記錄類型 = 7)
- 排程記錄 (記錄類型 = 8)
- 記錄記錄 (記錄類型 = 9)
- 大型 BLOB 記錄 (記錄類型 = 15，大型類型 = 0)
記錄標題
所有記錄都包含這個標頭，其中會指定記錄的類型和大小，以及 48 位元的資料，這些資料的用途會因記錄類型而異。
格式
標頭字詞
[0 .. 3]：記錄類型[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 63]：因記錄類型而異 (如未使用，則必須為零)
大型記錄標頭
支援超過 32 KB 的記錄。大型記錄的 32 位元大小欄位，而非一般 12 位元。
標頭字詞
[0 .. 3]：記錄類型 (15)[4 .. 35]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[36 .. 39]：大型記錄類型[40 .. 63]：因大型記錄類型而異 (如未使用，則必須為零)
中繼資料記錄 (記錄類型 = 0)
提供後續追蹤資料的中繼資料。
產生追蹤記錄封存檔時，追蹤記錄管理員會保留這個記錄類型。追蹤記錄供應商本身不得發出這類事件。 如果追蹤記錄管理工具在追蹤記錄提供者產生的追蹤記錄中，發現中繼資料記錄，就會將其視為垃圾資料並略過。
中繼資料記錄有多個子類型，每個子類型都包含不同的資訊。
格式
標頭字詞
[0 .. 3]：記錄類型 (0)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 19]：中繼資料類型[20 .. 63]：視中繼資料類型而異 (如未使用則必須為零)
供應商資訊中繼資料 (中繼資料類型 = 1)
這項中繼資料會識別為追蹤記錄提供資訊的追蹤記錄供應商。
在遇到下一個供應商區段中繼資料或供應商資訊中繼資料之前，所有後續資料都必須來自同一供應商。
格式
標頭字詞
[0 .. 3]：記錄類型 (0)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 19]：中繼資料類型 (1)[20 .. 51]：供應商 ID (用於在追蹤記錄中識別供應商的權杖)[52 .. 59]：名稱長度 (以位元組為單位)[60 .. 63]：保留 (必須為零)
供應商名稱串流
- UTF-8 字串，以零填補至 8 位元組對齊
供應商區段中繼資料 (中繼資料類型 = 2)
這項中繼資料會劃分從不同供應商取得的追蹤記錄區段。
在遇到下一個供應商區段中繼資料或供應商資訊中繼資料之前，系統會假設所有後續資料都是從同一供應商收集而來。
讀取由不同追蹤記錄供應商累積的追蹤記錄時，讀取器必須為每個供應商的追蹤記錄分別維護狀態 (例如初始化資料、字串表、執行緒表、使用者空間物件表和核心物件表)，並在遇到新的供應商區段中繼資料記錄時切換環境。
格式
標頭字詞
[0 .. 3]：記錄類型 (0)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 19]：中繼資料類型 (2)[20 .. 51]：供應商 ID (用於在追蹤記錄中識別供應商的權杖)[52 .. 63]：保留 (必須為零)
供應商事件中繼資料 (中繼資料類型 = 3)
這項中繼資料會提供供應商想回報的事件即時通知。
這項記錄可能會出現在輸出內容的任何位置，且不會分隔前後的內容。
格式
標頭字詞
[0 .. 3]：記錄類型 (0)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 19]：中繼資料類型 (3)[20 .. 51]：供應商 ID (用於在追蹤記錄中識別供應商的權杖)[52 .. 55]：活動 ID[56 .. 63]：保留 (必須為零)
活動
系統會定義下列事件。
0：緩衝區已滿，可能已捨棄記錄
追蹤資訊中繼資料 (中繼資料類型 = 4)
這項中繼資料提供有關追蹤記錄的整體資訊。這筆記錄未與特定供應商建立關聯。
格式
標頭字詞
[0 .. 3]：記錄類型 (0)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 19]：中繼資料類型 (4)[20 .. 23]：追蹤資訊類型[24 .. 63]：因追蹤資訊類型而異 (如未使用，則必須為零)
魔術數字記錄 (追蹤資訊類型 = 0)
這項記錄可做為指標，指出二進位資料採用 Fuchsia 追蹤格式。一般來說，這項指標應會出現在追蹤記錄的開頭。不含其他資訊。神奇數字 0x16547846 是指「FxT」字串，後面接著隨機選擇的位元組。
如要允許將追蹤記錄的前八個位元組視為魔術數字，而不必在意內部記錄結構，這個記錄類型不可擴充。記錄不得包含標頭字詞以外的任何字詞，且沒有保留欄位。以八位元組數字來說，整個記錄的值為 0x0016547846040010。
請注意，該值和追蹤記錄中所有其他字組的位元組順序，取決於寫入追蹤記錄的系統的位元組順序。如果是小端系統，前八個位元組為 10 00 04 46 78 54 16 00。在大端系統上，順序會相反：00 16 54 78 46 04 00 10。
格式
標頭字詞
[0 .. 3]：記錄類型 (0)[4 .. 15]：記錄大小 (含這個字)，以 8 個位元組的倍數表示 (1)[16 .. 19]：中繼資料類型 (4)[20 .. 23]：追蹤資訊類型 (0)[24 .. 55]：魔術數字 0x16547846[56 .. 63]：零
初始化記錄 (記錄類型 = 1)
提供解讀後續記錄所需的參數。如果沒有這筆記錄，讀者可能會假設 1 個刻度等於 1 奈秒。
格式
標頭字詞
[0 .. 3]：記錄類型 (1)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 63]：保留 (必須為零)
勾號乘數字詞
[0 .. 63]：每秒的刻度數
字串記錄 (記錄類型 = 2)
在字串資料表中註冊字串，並在 0x0001 至 0x7fff 範圍內指派字串索引。解讀後續記錄時，註冊會取代指定字串索引的任何先前註冊。
嘗試為字串索引 0x0000 設定值的字串記錄必須忽略，因為這個值保留用於代表空字串。
含有空字串的字串記錄必須容許，但這類記錄毫無意義，因為空字串可以簡單地編碼為字串參照中的零。
格式
標頭字詞
[0 .. 3]：記錄類型 (2)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 30]：字串索引 (範圍為 0x0001 至 0x7fff)[31]：一律為零 (0)[32 .. 46]：字串長度 (以位元組為單位，範圍為 0x0000 至 0x7fff)[47]：一律為零 (0)[48 .. 63]：保留 (必須為零)
字串值串流
- UTF-8 字串，以零填補至 8 位元組對齊
執行緒記錄 (記錄類型 = 3)
在執行緒表格中註冊程序 ID 和執行緒 ID 配對，並在 0x01 至 0xff 範圍內指派執行緒索引。解讀後續記錄時，註冊會取代指定執行緒索引的任何先前註冊。
執行緒索引 0x00 保留用於表示執行緒參照中的內嵌執行緒 ID。嘗試為這個值設定值的執行緒記錄必須忽略。
格式
標頭字詞
[0 .. 3]：記錄類型 (3)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 23]：執行緒索引 (絕不會是 0x00)[24 .. 63]：保留 (必須為零)
process id word
[0 .. 63]：程序 koid (核心物件 ID)
thread id word
[0 .. 63]：執行緒 koid (核心物件 ID)
事件記錄 (記錄類型 = 4)
說明有時間戳記的事件。
這項記錄包含事件的基本資訊，包括發生時間和地點，以及事件引數和事件子類型專屬資料。
格式
標頭字詞
[0 .. 3]：記錄類型 (4)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 19]：活動類型[20 .. 23]：引數數量[24 .. 31]：執行緒 (執行緒參照)[32 .. 47]：類別 (字串參照)[48 .. 63]：名稱 (字串參照)
時間戳記字詞
[0 .. 63]：刻度數
程序 ID 字詞 (省略，除非執行緒參照表示內嵌執行緒)
[0 .. 63]：程序 koid (核心物件 ID)
執行緒 ID 字詞 (除非執行緒參照表示內嵌執行緒，否則會省略)
[0 .. 63]：執行緒 koid (核心物件 ID)
category stream (省略，除非字串參照表示內嵌字串)
- UTF-8 字串，以零填補至 8 位元組對齊
name stream (省略，除非字串參照表示內嵌字串)
- UTF-8 字串，以零填補至 8 位元組對齊
引數資料 (每個引數重複一次)
- (詳情請見下方)
特定事件類型資料
- 可以是下列任一值：
即時活動 (活動類型 = 0)
標示這個執行緒中的某個時間點。這等同於 Zircon 核心探測。
格式
不需要特定事件類型的資料。
計數器事件 (事件類型 = 1)
記錄每個引數的樣本值，做為與計數器名稱和 ID 相關聯的時間序列資料。這些值可能會以堆疊面積圖呈現。
格式
反向字詞
[0 .. 63]：計數器 ID
持續時間開始事件 (事件類型 = 2)
標示特定執行緒上作業的開頭。必須與時間長度結束事件相符。可為巢狀結構。
格式
不需要特定事件類型的資料。
持續時間結束事件 (事件類型 = 3)
標示特定執行緒上作業的結尾。
格式
不需要特定事件類型的資料。
完成時間長度事件 (事件類型 = 4)
標記特定執行緒上作業的開始和結束時間。
格式
結束時間字詞
[0 .. 63]：結束時間的刻度數
非同步開始事件 (事件類型 = 5)
標記可能跨執行緒的作業開頭。必須使用相同的非同步關聯 ID，與非同步結束事件相符。
格式
非同步關聯字詞
[0 .. 63]：非同步關聯性 ID
非同步即時事件 (事件類型 = 6)
標記作業中的某個時間點，該作業可能跨越多個執行緒。必須出現在非同步開始事件和非同步結束事件之間，且使用相同的非同步關聯 ID。
格式
非同步關聯字詞
[0 .. 63]：非同步關聯性 ID
非同步結束事件 (事件類型 = 7)
標記可能跨執行緒的作業結束。
格式
非同步關聯字詞
[0 .. 63]：非同步關聯性 ID
流程開始事件 (事件類型 = 8)
標記作業的開頭，這會產生一連串可能跨越多個執行緒或抽象層的動作。必須由使用相同流程關聯 ID 的流程結束事件比對。這可以想像成是時間長度事件之間的箭頭。
流程的開頭與這個執行緒的封閉式時間長度事件相關聯；流程的開頭是封閉式時間長度事件的結尾。
格式
流程關聯字
[0 .. 63]：流程關聯性 ID
流程步驟事件 (事件類型 = 9)
標記流程中的某個點。
這個步驟與這個執行緒的封閉式持續時間事件相關聯；流程會在封閉式持續時間事件開始時繼續執行，然後在封閉式持續時間事件結束時暫停。
格式
流程關聯字
[0 .. 63]：流程關聯性 ID
流程結束事件 (事件類型 = 10)
標示流程的結尾。
流程的結尾與這個執行緒的封閉式持續時間事件相關聯；流程會在封閉式持續時間事件開始的位置繼續執行。
格式
流程關聯字
[0 .. 63]：流程關聯性 ID
BLOB 記錄 (記錄類型 = 5)
提供要納入追蹤記錄的未解譯大量資料。這項功能有助於以其他格式嵌入擷取的追蹤資料。
Blob 名稱可唯一識別追蹤記錄中的個別 Blob 資料串流。 撰寫多筆同名 Blob 記錄時，可將額外的資料區塊附加至先前建立的 BLOB。
BLOB 類型表示 BLOB 的內容。
格式
標頭字詞
[0 .. 3]：記錄類型 (5)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 31]：Blob 名稱 (字串參照)[32 .. 46]：以位元組為單位的 Blob 酬載大小 (不含邊框間距)[47 .. 47]：保留 (必須為零)[48 .. 55]：blob 類型[56 .. 63]：保留 (必須為零)
blob name stream (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
酬載串流 (大小可變)
- 二進位資料，以零填補至 8 位元組對齊
Blob 類型
定義的 Blob 類型如下：
TRACE_BLOB_TYPE_DATA=0x01：原始未輸入資料。取用端應知道如何取用，或許是根據情境。TRACE_BLOB_TYPE_LAST_BRANCH=0x02：Intel Performance Monitor 的最後分支記錄。 格式由 CPU 效能監控器定義。TRACE_BLOB_TYPE_PERFETTO =0x03：這個 Blob 包含從 Perfetto 說話元件記錄的資料。資料會以 Perfetto 的 Proto 格式編碼。
使用者空間物件記錄 (記錄類型 = 6)
說明使用者空間物件、指派標籤，並視需要將鍵/值資料與其建立關聯做為引數。物件的相關資訊會新增至每個程序的物件表。
當追蹤記錄消費者遇到具有指標引數的事件，且該引數的值與程序物件表格中的項目相符時，即可將引數的指標值與先前的使用者空間物件記錄交叉參照，找出參照物件的說明。
格式
標頭字詞
[0 .. 3]：記錄類型 (6)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 23]：程序 (執行緒參照)[24 .. 39]：名稱 (字串參照)[40 .. 43]：引數數量[44 .. 63]：保留 (必須為零)
指標字
[0 .. 63]：指標值
程序 ID 字詞 (省略，除非執行緒參照表示內嵌執行緒)
[0 .. 63]：程序 koid (核心物件 ID)
name stream (省略，除非字串參照表示內嵌字串)
- UTF-8 字串，以零填補至 8 位元組對齊
引數資料 (每個引數重複一次)
- (詳情請見下方)
核心物件記錄 (記錄類型 = 7)
說明核心物件、指派標籤，並視需要將鍵/值資料與其建立關聯做為引數。物件相關資訊會新增至全域核心物件表格。
當追蹤記錄消費者遇到含有 koid 引數的事件，且該引數的值與核心物件表中的項目相符時，可以交叉參照引數的 koid 值與先前的核心物件記錄，找出參照物件的說明。
格式
標頭字詞
[0 .. 3]：記錄類型 (7)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 23]：核心物件類型 (來自 zircon/syscalls/types.h 的 ZX_OBJ_TYPE_XXX 常數之一)[24 .. 39]：名稱 (字串參照)[40 .. 43]：引數數量[44 .. 63]：保留 (必須為零)
核心物件 ID 字詞
[0 .. 63]：koid (核心物件 ID)
name stream (省略，除非字串參照表示內嵌字串)
- UTF-8 字串，以零填補至 8 位元組對齊
引數資料 (每個引數重複一次)
- (詳情請見下方)
引數慣例
依慣例，追蹤記錄寫入器應在寫入特定類型物件的核心物件記錄時，加入下列具名引數。這有助於追蹤消費者在核心物件間的關聯性。
"process"：針對ZX_OBJ_TYPE_THREAD物件，指定包含執行緒的程序 koid
排程記錄 (記錄類型 = 8)
說明排程事件，例如喚醒執行緒的時間，或從一個執行緒切換到另一個執行緒的內容。
格式
+---------(4)--------------+--------(48)--------+--(8)--+-(4)-+
| scheduling record type | <type specific> | size | 8 |
+--------------------------+--------------------+-------+-----+
標頭字詞
[0 .. 3]：記錄類型 (8)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 59]：排定記錄類型專屬資料的時程[60 .. 63]：排程記錄類型
內容切換記錄 (排程事件記錄類型 = 1)
格式
+-(4)-+----(20)---+--------(4)-------+----(16)---+-------(4)-------+----(8)--+-(4)-+
| 1 | reserved | out thread state | cpu | argument count | size | 8 |
+-----+-----------+------------------+-----------+-----------------+---------+-----+
+---------------------------(64)------------------------------+
| timestamp |
+-------------------------------------------------------------+
+---------------------------(64)------------------------------+
| outgoing thread id |
+-------------------------------------------------------------+
+---------------------------(64)------------------------------+
| incoming thread id |
+-------------------------------------------------------------+
+--------------------------(...)------------------------------+
| argument data |
+-------------------------------------------------------------+
標頭字詞
[0 .. 3]：記錄類型 (8)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 19]：引數計數[20 .. 35]：CPU 編號[36 .. 39]：傳出執行緒狀態[40 .. 59]：保留[60 .. 63]：排程記錄類型 (1)
時間戳記字詞
[0 .. 63]：刻度數
outoing 執行緒 id
[0 .. 63]：執行緒 koid (核心物件 ID)
傳入的執行緒 ID
[0 .. 63]：執行緒 koid (核心物件 ID)
引數資料 (每個引數的重複項目)
- (引數格式請參閱「引數」)
引數慣例
依慣例，追蹤記錄寫入器也可以選擇在寫入這項記錄時，加入下列具名引數，為追蹤記錄消費者提供額外資訊。
"incoming_weight"：Int32，說明傳入執行緒的相對權重"outgoing_weight"：Int32，說明外送執行緒的相對權重
執行緒喚醒記錄 (排程事件記錄類型 = 2)
格式
+-(4)-+----(24)---+----(16)---+-------(4)-------+----(8)--+-(4)-+
| 2 | reserved | cpu | argument count | size | 8 |
+-----+-----------+-----------+-----------------+---------+-----+
+---------------------------(64)------------------------------+
| timestamp |
+-------------------------------------------------------------+
+---------------------------(64)------------------------------+
| waking thread id |
+-------------------------------------------------------------+
+--------------------------(...)------------------------------+
| argument data |
+-------------------------------------------------------------+
標頭字詞
[0 .. 3]：記錄類型 (8)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 19]：引數計數。[20 .. 35]：CPU 編號。[60 .. 63]：排程記錄類型 (2)
時間戳記字詞
[0 .. 63]：刻度數
waking 執行緒 id
[0 .. 63]：執行緒 koid (核心物件 ID)
引數資料 (每個引數的重複項目)
- (引數格式請參閱「引數」)
引數慣例
依慣例，追蹤記錄寫入器也可以視需要加入下列具名引數，在寫入這項記錄時提供額外資訊給追蹤記錄消費者。
"weight"：Int32，說明喚醒執行緒的相對權重
舊版內容切換記錄 (內容切換記錄類型 = 0)
隨著 Fuchsia 的排程演進，這項記錄已不再是有效的內容切換模型。但仍保留這個屬性，以確保回溯相容性。
這項記錄會指定內容切換後，外送執行緒的新狀態。根據定義，由於傳入的執行緒剛恢復執行，因此新狀態為「執行中」。
格式
[0 .. 3]：記錄類型 (8)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 23]：CPU 編號[24 .. 27]：傳出執行緒狀態 (下列任一值，但「執行中」除外)[28 .. 35]：外送執行緒 (執行緒參照)[36 .. 43]：傳入的執行緒 (執行緒參照)[44 .. 51]：外送執行緒優先順序[52 .. 59]：傳入的執行緒優先順序[60 .. 63]：排程記錄類型 (0)
時間戳記字詞
[0 .. 63]：刻度數
outgoing process id word (除非外送執行緒參照表示內嵌執行緒，否則會省略)
[0 .. 63]：程序 koid (核心物件 ID)
outgoing 執行緒 id word (除非外送會話串參照表示內嵌執行緒，否則會省略)
[0 .. 63]：執行緒 koid (核心物件 ID)
傳入程序 ID 字詞 (省略，除非傳入的執行緒參照表示內嵌執行緒)
[0 .. 63]：程序 koid (核心物件 ID)
傳入的執行緒 ID 字詞 (除非傳入的執行緒參照表示內嵌執行緒，否則會省略)
[0 .. 63]：執行緒 koid (核心物件 ID)
執行緒狀態
定義的執行緒狀態如下：
0：新1：執行中2：已暫停3：已封鎖4：快沒電5：已停止
這些值與 zircon/syscalls/object.h 中的 ZX_THREAD_STATE_XXX 常數一致。
記錄記錄 (記錄類型 = 9)
說明在特定時間點寫入記錄的訊息。
格式
標頭字詞
[0 .. 3]：記錄類型 (9)[4 .. 15]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[16 .. 30]：記錄訊息長度 (以位元組為單位，範圍為 0x0000 至 0x7fff)[31]：一律為零 (0)[32 .. 39]：執行緒 (執行緒參照)[40 .. 63]：保留 (必須為零)
時間戳記字詞
[0 .. 63]：刻度數
程序 ID 字詞 (省略，除非執行緒參照表示內嵌執行緒)
[0 .. 63]：程序 koid (核心物件 ID)
執行緒 ID 字詞 (除非執行緒參照表示內嵌執行緒，否則會省略)
[0 .. 63]：執行緒 koid (核心物件 ID)
記錄訊息串流
- UTF-8 字串，以零填補至 8 位元組對齊
大型 BLOB 記錄 (記錄類型 = 15，大型類型 = 0)
提供要嵌入追蹤記錄中的大型二進位 BLOB 資料。它會使用大型記錄標頭。
大型 BLOB 記錄支援多種不同格式。這些格式可用於變更記錄中包含的 BLOB 資料和中繼資料類型。
格式
標頭字詞
[0 .. 3]：記錄類型 (15)[4 .. 35]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[36 .. 39]：大型記錄類型 (0)[40 .. 43]：Blob 格式類型[44 .. 63]：保留，必須為零
在 Band Large Blob Record With Metadata (blob format = 0) 中
這個型別包含記錄本身的 Blob 資料和中繼資料。中繼資料除了類別和名稱外，還包含時間戳記、執行緒/程序資訊和引數。
名稱應足以識別 Blob 內含的資料類型。
格式
標頭字詞
[0 .. 3]：記錄類型 (15)[4 .. 35]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[36 .. 39]：大型記錄類型 (0)[40 .. 43]：Blob 格式類型 (0)[44 .. 63]：保留，必須為零
格式標題字詞
[0 .. 15]：類別 (字串參照)[16 .. 31]：名稱 (字串參照)[32 .. 35]：引數數量[36 .. 43]：執行緒 (執行緒參照)[44 .. 63]：保留，必須為零
category stream (省略，除非字串參照表示內嵌字串)
- UTF-8 字串，以零填補至 8 位元組對齊
name stream (省略，除非字串參照表示內嵌字串)
- UTF-8 字串，以零填補至 8 位元組對齊
時間戳記字詞
[0 .. 63]：刻度數
程序 ID 字詞 (省略，除非執行緒參照表示內嵌執行緒)
[0 .. 63]：程序 koid (核心物件 ID)
執行緒 ID 字詞 (除非執行緒參照表示內嵌執行緒，否則會省略)
[0 .. 63]：執行緒 koid (核心物件 ID)
引數資料 (每個引數重複一次)
- (詳情請見下方)
blob size word
[0 .. 63]：以位元組為單位的 Blob 酬載大小 (不含邊框間距)
酬載串流 (大小可變)
- 二進位資料，以零填補至 8 位元組對齊
頻帶大型 Blob 記錄中沒有中繼資料 (Blob 格式 = 1)
這種類型包含記錄中的 Blob 資料本身，但不包含中繼資料。記錄只包含類別和名稱。
名稱應足以識別 Blob 內含的資料類型。
格式
標頭字詞
[0 .. 3]：記錄類型 (15)[4 .. 35]：記錄大小 (包括這個字)，以 8 位元組的倍數表示[36 .. 39]：大型記錄類型 (0)[40 .. 43]：Blob 格式類型 (1)[44 .. 63]：保留，必須為零
格式標題字詞
[0 .. 15]：類別 (字串參照)[16 .. 31]：名稱 (字串參照)[32 .. 63]：保留，必須為零
category stream (省略，除非字串參照表示內嵌字串)
- UTF-8 字串，以零填補至 8 位元組對齊
name stream (省略，除非字串參照表示內嵌字串)
- UTF-8 字串，以零填補至 8 位元組對齊
blob size word
[0 .. 63]：以位元組為單位的 Blob 酬載大小 (不含邊框間距)
酬載串流 (大小可變)
- 二進位資料，以零填補至 8 位元組對齊
引數類型
引數會將型別鍵和值資料記錄建立關聯。這些記錄會與事件記錄、使用者空間物件記錄和核心物件記錄一併使用。
每個引數都包含一個字的首部，後接可變數量的酬載字。在許多情況下，標頭本身就足以編碼引數的內容。
引數類型如下：
- 引數標題
- 空值引數
- 32 位元帶正負號整數引數
- 32 位元不帶正負號整數引數
- 64 位元帶正負號整數引數
- 64 位元不帶正負號整數引數
- 雙精度浮點引數
- 字串引數
- 指標引數
- 核心物件 ID 引數
- 布林引數
- Blob 引數
引數標頭
所有引數都包含這個標頭，其中會指定引數的型別、名稱和大小，以及 32 位元的資料，用途會因引數型別而異。
格式
引數標頭字詞
[0 .. 3]：引數類型[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：視情況而定 (如未使用，則必須為零)
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
空值引數 (引數類型 = 0)
代表只顯示名稱的引數，沒有值。
格式
引數標頭字詞
[0 .. 3]：引數型別 (0)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：保留 (必須為零)
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
32 位元帶正負號整數引數 (引數類型 = 1)
代表 32 位元帶正負號整數。
格式
引數標頭字詞
[0 .. 3]：引數類型 (1)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：32 位元帶正負號整數
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
32 位元不帶正負號整數引數 (引數類型 = 2)
代表 32 位元不帶正負號的整數。
格式
引數標頭字詞
[0 .. 3]：引數類型 (2)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：32 位元不帶正負號的整數
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
64 位元帶正負號整數引數 (引數類型 = 3)
代表 64 位元帶正負號整數。如果值適合 32 位元，請改用 32 位元帶正負號的整數引數型別。
格式
引數標頭字詞
[0 .. 3]：引數類型 (3)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：保留 (必須為零)
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
引數值字詞
[0 .. 63]：64 位元帶正負號整數
64 位元不帶正負號整數引數 (引數類型 = 4)
代表 64 位元無正負號整數。如果值適合 32 位元，請改用 32 位元不帶正負號的整數引數型別。
格式
引數標頭字詞
[0 .. 3]：引數類型 (4)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：保留 (必須為零)
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
引數值字詞
[0 .. 63]：64 位元不帶正負號整數
雙精度浮點引數 (引數類型 = 5)
代表雙精度浮點數。
格式
引數標頭字詞
[0 .. 3]：引數類型 (5)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：保留 (必須為零)
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
引數值字詞
[0 .. 63]：雙精度浮點數
字串引數 (引數類型 = 6)
代表字串值。
格式
引數標頭字詞
[0 .. 3]：引數類型 (6)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 47]：引數值 (字串參照)[48 .. 63]：保留 (必須為零)
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
引數值串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
指標引數 (引數類型 = 7)
代表指標值。與相同指標相關聯的使用者空間物件記錄，可提供參照的其他資訊。
格式
引數標頭字詞
[0 .. 3]：引數類型 (7)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：保留 (必須為零)
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
引數值字詞
[0 .. 63]：指標值
核心物件 ID 引數 (引數類型 = 8)
代表 koid (核心物件 ID)。與相同 koid 相關聯的核心物件記錄可提供參照的其他資訊。
格式
引數標頭字詞
[0 .. 3]：引數類型 (8)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：保留 (必須為零)
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
引數值字詞
[0 .. 63]：koid (核心物件 ID)
布林引數 (引數類型 = 9)
代表布林值。
格式
引數標頭字詞
[0 .. 3]：引數類型 (9)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：以零填補的 1 位元
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
Blob 引數 (引數類型 = 10)
代表不透明的二進位資料。大小上限略小於 32k。
格式
引數標頭字詞
[0 .. 3]：引數類型 (10)[4 .. 15]：引數大小 (包括這個字) 為 8 位元組的倍數[16 .. 31]：引數名稱 (字串參照)[32 .. 63]：32 位元不帶正負號的 Blob 大小
引數名稱串流 (除非字串參照表示內嵌字串，否則會省略)
- UTF-8 字串，以零填補至 8 位元組對齊
酬載串流
- 二進位資料，以零填補至 8 位元組對齊
- 標頭會佔用 8 個位元組，內嵌引數名稱則會佔用 8 個位元組，因此最大大小為 32k 減去這些位元組。
- 由於酬載串流可能會經過填補，讀取器應捨棄超出 blob 大小標頭欄位指定長度的位元組。