本文說明用來收集、儲存及傳送 Fuchsia 追蹤記錄記錄的二進位格式。您可以使用本文件,搜尋 Fuchsia 追蹤記錄格式中每個欄位的詳細資訊。
簡介
在追蹤記錄執行時,追蹤提供者會使用本文件所述的二進位格式,將記錄寫入與追蹤記錄管理員共用的追蹤緩衝區 VMO。
二進位格式旨在在編寫追蹤記錄時,盡可能降低對追蹤主體效能的影響。這些記錄也會依序寫入,因此若追蹤記錄終止 (正常或異常),追蹤管理員仍可讀取完整記錄格式的所有資料,藉此復原已儲存在追蹤記錄緩衝區中的部分追蹤記錄資料。
在追蹤記錄的進展時,追蹤記錄管理員會匯總所有參與追蹤記錄提供者的記錄,然後將其與某些特殊中繼資料記錄串連在一起,以形成追蹤記錄封存。
追蹤記錄完成後,trace
指令列程式等工具可以讀取追蹤記錄封存檔中的追蹤記錄,以視覺化方式呈現結果,或將結果儲存至檔案供日後使用。
功能
- 佔用空間不大
- 追蹤記錄是精簡的,將資訊封裝成少量位元。
- 集區字串、程序和執行緒會進一步壓縮追蹤記錄資料。
- 記憶體已對齊
- Trace 記錄會保留記憶體中的 8 位元組對齊,以便直接將記錄寫入記憶體對應的 VMO。
- 變數大小記錄
- 整體記錄大小的上限為 32 KB。
- 大型物件可能需要拆分為多項記錄,
- 可擴充
- 可視需要定義新的記錄類型。
- 您可以略過無法辨識或格式錯誤的追蹤記錄。
編碼基本
Fuchsia 追蹤格式採用下列編碼原始格式:
原子
每筆記錄都是建構成一系列原子。
每個 Atom 都以 8 位元組對齊方式編寫,大小也是 8 個位元組的倍數,因此為保持對齊。
原子分為兩種:
- Word:可進一步細分為位元欄位的 64 位元值。字詞會按照機器字詞順序儲存 (在所有目前支援的架構中,小至端)。
- 串流:在下一個 8 位元組邊界填充的位元組序列。串流會以位元組順序儲存。長度剛好為 8 個位元組的多個串流不會填補 (沒有終止器)。
「欄位」是 64 位元 Words 的子區域,以 [<least significant bit> .. <most significant bit>]
表示,第一個和最後一個位元位置包含此項目。所有未使用的位元都會保留供日後使用,且必須設為 0。
除非記錄格式另外指定,否則「Words」和「Fields」會儲存無正負號整數。
串流可儲存 UTF-8 字串或二進位資料,如記錄格式指定。
記錄
追蹤記錄是經過二進位編碼的追蹤記錄資訊,由 atoms 序列組成。
所有記錄都會含有包含下列基本資訊的標頭字詞:
- 記錄類型:用於識別記錄類型和其中資訊的 4 位元欄位。請參閱記錄類型。
- 記錄大小:通常為 12 位元欄位,指出記錄內包含記錄標頭本身的字詞數 (8 個位元組的倍數)。記錄大小上限為 4,095 個字 (32760 個位元組)。非常簡單的記錄可能只有 1 個字 (8 個位元組)。大型記錄會使用 32 位元大小欄位,因此大小上限較高。
記錄長度一律為 8 個位元組的倍數,且以 8 位元組對齊的方式儲存。
封存
追蹤記錄封存是一系列由端對端串連的追蹤記錄,用於儲存追蹤記錄供應商在執行時收集的資訊,以及相關中繼資料記錄,以便識別及分隔各個追蹤服務供應商產生的追蹤記錄區段。
追蹤記錄封存是按順序讀取,因為較早顯示在追蹤記錄中的記錄可能會影響如何解讀追蹤記錄中稍後顯示的記錄。追蹤系統提供實用工具,可讓您從追蹤記錄封存資料中擷取資訊,並將資訊轉換為其他形式,以便進行視覺化。
時間戳記
時間戳記是以硬體計數器衍生的 64 位元滴答聲表示。追蹤記錄初始化記錄會說明即時每秒跳轉次數。
根據預設,我們假設 1 個刻度等於 1 奈秒。
字串參照
字串會編碼為 String Refs,也就是 16 位元的值,格式如下:
- 空白字串:值為零。
- 已建立索引的字串:最重要的位元為零。較低的 15 位元代表字串資料表中的索引 (先前使用字串記錄指派)。
- 內嵌字串:最重要的位元就是一個。較低的 15 位元代表字串長度 (以位元組為單位)。字串的內容會顯示在記錄格式指定的其他記錄部分。
如要讓追蹤記錄更精簡,經常參照的字串 (例如事件類別和名稱常數) 應使用字串記錄,然後透過索引參照,在字串表中註冊。
字串資料表中最多只能有 32767 個字串。如果達到此限制,可藉由替換現有項目或內嵌編碼字串來編碼其他字串。
字串內容本身會以 UTF-8 串流的形式儲存,而不會終止。
字串的理論長度上限是 32767 個位元組,但實際上,這個數值會進一步減少儲存含有該記錄的其餘記錄所需的空間,因此我們將字串長度上限設為 32, 000 個位元組。
執行緒參照
執行緒和程序核心物件 ID (koid) 會編碼為「執行緒參照」,格式如下:8 位元值:
- 內嵌執行緒:值為零。執行緒和程序 koid 會內嵌在記錄格式指定的記錄另一部分。
- 已建立索引的執行緒:這個值不為零。此值表示執行緒資料表中先前使用執行緒記錄指派的索引。
如要使追蹤記錄更精簡,常用的參照執行緒應使用執行緒記錄註冊至執行緒資料表,然後再以索引參照。
字串資料表中最多只能有 255 個執行緒。如果達到此限制,可藉由取代現有項目或以內嵌方式編碼執行緒,將其他執行緒編碼。
Userspace 物件資訊
追蹤記錄可包含使用者空間物件的註解 (可使用指標型值,例如 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)
提供後續追蹤資料的相關中繼資料。
在產生追蹤記錄封存時,這個記錄類型會保留給 trace Manager 使用。不得由追蹤提供者本身發出。如果追蹤記錄管理員在追蹤提供者產生的追蹤記錄中遇到中繼資料記錄,就會將其視為垃圾並略過。
有多個中繼資料記錄子類型,每個類型都包含不同的資訊。
格式
標頭字詞
[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 字串,填充為 0 到 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 字串,填充為 0 到 8 位元組的對齊
執行緒記錄 (記錄類型 = 3)
在執行緒資料表中註冊程序 ID 和執行緒 ID 配對,並為其指派 0x01
範圍內的執行緒索引至 0xff
。註冊機制會在解讀後續記錄時,取代指定執行緒索引先前的註冊資料。
執行緒索引 0x00
已保留,用於在執行緒參照中使用內嵌執行緒 ID。您必須忽略嘗試設定這個值的執行緒記錄。
格式
標頭字詞
[0 .. 3]
:記錄類型 (3)[4 .. 15]
:記錄大小 (含這個字詞),以 8 個位元組的倍數表示[16 .. 23]
:執行緒索引 (一律不 0x00)[24 .. 63]
:保留 (必須為零)
[0 .. 63]
:程序 koid (核心物件 ID)
執行緒 ID 字詞
[0 .. 63]
:執行緒 koid (核心物件 ID)
事件記錄 (記錄類型 = 4)
說明已加上時間戳記的事件。
這個記錄包含事件的部分基本資訊,包括事件引數和事件子類型的特定資料。
格式
標頭字詞
[0 .. 3]
:記錄類型 (4)[4 .. 15]
:記錄大小 (含這個字詞),以 8 個位元組的倍數表示[16 .. 19]
:事件類型[20 .. 23]
:引數數量[24 .. 31]
:執行緒 (執行緒參考資料)[32 .. 47]
:類別 (字串參照)[48 .. 63]
:名稱 (字串參照)
時間戳記字詞
[0 .. 63]
:刻點數
Process id word (程序 ID 字詞;除非執行緒參照代表內嵌執行緒)
[0 .. 63]
:程序 koid (核心物件 ID)
thread id word (除非執行緒參照為內嵌執行緒,否則會省略)
[0 .. 63]
:執行緒 koid (核心物件 ID)
類別串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
引數資料 (每個引數重複)
- (詳情請參閱下方)
事件類型專屬資料
- 可以是下列任一值:
即時事件 (事件類型 = 0)
標示這個執行緒中的某個時間。這相當於 Zircon 核心探測器。
格式
無須提供事件類型專屬資料。
計數器事件 (事件類型 = 1)
將每個引數的範例值記錄為與計數器名稱和 ID 相關聯的時間序列中的資料。這些值可透過圖形呈現為堆疊面積圖。
格式
計數器字詞
[0 .. 63]
:計數器 ID
持續時間開始事件 (事件類型 = 2)
標示特定執行緒上作業的開始。必須與時間長度結束事件進行比對。可使用巢狀結構。
格式
無須提供事件類型專屬資料。
持續時間結束事件 (事件類型 = 3)
在特定執行緒上標示作業結束。
格式
無須提供事件類型專屬資料。
完成事件持續時間 (事件類型 = 4)
在特定執行緒上標示作業開始和結束。
格式
結束時間文字
[0 .. 63]
:刻點結束時間
Async begin event (event type = 5)
標示可能橫跨執行緒的作業開頭。必須使用相同的非同步關聯 ID,由非同步結束事件進行比對。
格式
async correlation word
[0 .. 63]
: async correlation id
非同步即時事件 (事件類型 = 6)
標示可能橫跨執行緒的作業的時刻。必須在「非同步開始事件」async begin event和「非同步結束事件」async begin event之間顯示,且必須使用相同的非同步關聯 ID。
格式
async correlation word
[0 .. 63]
: async correlation id
Async end event (event type = 7)
標示可能橫跨執行緒的作業結束。
格式
async correlation word
[0 .. 63]
: async correlation id
流程開始事件 (事件類型 = 8)
標示作業的開頭,進而產生橫跨多個執行緒或抽象層的動作序列。必須與使用相同資料流關聯 ID 的資料流結束事件進行比對。這可以顯示在持續時間事件之間以箭頭表示。
流程的開始與此執行緒的涵蓋持續時間事件相關;系統會從封閉的持續時間事件結束的地方開始。
格式
文字流相關字
[0 .. 63]
:流量相關 ID
流程步驟事件 (事件類型 = 9)
在流程內標示一個點。
該步驟與此執行緒的涵蓋持續時間事件相關聯;系統會從涵蓋持續時間事件開始時恢復流程,然後會在包含的 duration 事件事件結束時暫停。
格式
文字流相關字
[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 名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
酬載串流 (可變大小)
- 二進位資料,填充零到 8 位元組
Blob 類型
以下 blob 類型的定義如下:
TRACE_BLOB_TYPE_DATA
=0x01
:原始未經類型的資料。而消費者應知道如何消費 (可能以情境為基礎)。TRACE_BLOB_TYPE_LAST_BRANCH
=0x02
:Intel 效能監控器的最新分支版本記錄。格式由 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]
:指標值
Process id word (程序 ID 字詞;除非執行緒參照代表內嵌執行緒)
[0 .. 63]
:程序 koid (核心物件 ID)
名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 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)
名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 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]
:刻點數
[0 .. 63]
:執行緒 koid (核心物件 ID)
[0 .. 63]
:執行緒 koid (核心物件 ID)
引數資料 (重複輸入每個引數)
- (如需引數格式,請參閱 Arguments 部分)。
引數慣例
依照慣例,追蹤寫入器在寫入這筆記錄時也可以選擇加入下列已命名引數,以便向追蹤消費者提供額外資訊。
"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]
:刻點數
喚醒執行緒 ID
[0 .. 63]
:執行緒 koid (核心物件 ID)
引數資料 (重複輸入每個引數)
- (如需引數格式,請參閱 Arguments 部分)。
引數慣例
依照慣例,追蹤寫入者在編寫這筆記錄時也可以選擇加入下列已命名引數,以便向追蹤消費者提供額外資訊。
"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]
:刻點數
傳出程序 ID 字詞 (除非傳出執行緒參照代表內嵌執行緒)
[0 .. 63]
:程序 koid (核心物件 ID)
外寄執行緒 ID 字詞 (除非傳出討論串參照為內嵌執行緒,否則會省略)
[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]
:刻點數
Process id word (程序 ID 字詞;除非執行緒參照代表內嵌執行緒)
[0 .. 63]
:程序 koid (核心物件 ID)
thread id word (除非執行緒參照為內嵌執行緒,否則會省略)
[0 .. 63]
:執行緒 koid (核心物件 ID)
記錄訊息串流
- UTF-8 字串,填充為 0 到 8 位元組的對齊
大型 BLOB 記錄 (記錄類型 = 15,大型類型 = 0)
提供要嵌入追蹤記錄中的大型二進位 BLOB 資料。會使用大型記錄標頭。
大型 BLOB 記錄支援多種不同格式。這些格式可用於變更記錄中包含的 BLOB 資料類型和中繼資料。
格式
標頭字詞
[0 .. 3]
:記錄類型 (15)[4 .. 35]
:記錄大小 (含這個字詞),以 8 個位元組的倍數表示[36 .. 39]
:大型記錄類型 (0)[40 .. 43]
:blob 格式類型[44 .. 63]
:預留項目,必須是零
含有中繼資料的頻段大型 Blob 記錄 (blob 格式 = 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]
:預留項目,必須是零
類別串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
時間戳記字詞
[0 .. 63]
:刻點數
Process id word (程序 ID 字詞;除非執行緒參照代表內嵌執行緒)
[0 .. 63]
:程序 koid (核心物件 ID)
thread id word (除非執行緒參照為內嵌執行緒,否則會省略)
[0 .. 63]
:執行緒 koid (核心物件 ID)
引數資料 (每個引數重複)
- (詳情請參閱下方)
blob 大小字詞
[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]
:預留項目,必須是零
類別串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
blob 大小字詞
[0 .. 63]
:blob 酬載大小 (以位元組為單位,不含邊框間距)
酬載串流 (可變大小)
- 二進位資料,填充零到 8 位元組
引數類型
引數會連結已輸入的鍵和值資料記錄。它們會與事件記錄和使用者空間物件記錄和核心物件記錄搭配使用。
每個引數都包含一個字詞標頭,後接酬載的變數數字。在許多情況下,標頭本身就足以將引數的內容編碼。
引數類型如下:
- 引數標頭
- 空值引數
- 32 位元帶正負號整數引數
- 32 位元無正負號整數引數
- 64 位元帶正負號整數引數
- 64 位元無正負號整數引數
- 雙精度浮點引數
- 字串引數
- 遊標引數
- 核心物件 ID 引數
- 布林值引數
引數標頭
所有引數都會包含這個標頭,用於指定引數的類型、名稱和大小,以及 32 位元的資料,這些資料的用量會因引數類型而異。
格式
引數標頭字詞
[0 .. 3]
:引數類型[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:變化 (未使用時必須為零)
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
空值引數 (引數類型 = 0)
代表僅出現在名稱中的引數,且不含值。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (0)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:保留 (必須為零)
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
32 位元帶正負號整數引數 (引數類型 = 1)
代表 32 位元帶正負號整數。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (1)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:32 位元帶正負號整數
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
32 位元無正負號整數引數 (引數類型 = 2)
代表 32 位元無正負號整數。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (2)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:32 位元無正負號整數
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
64 位元帶正負號整數引數 (引數類型 = 3)
代表 64 位元帶正負號整數。如果值符合 32 位元,請改用 32 位元帶正負號整數引數類型。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (3)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:保留 (必須為零)
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
引數值字詞
[0 .. 63]
:64 位元帶正負號整數
64 位元無正負號整數引數 (引數類型 = 4)
代表 64 位元無正負號整數。如果值符合 32 位元,請改用 32 位元無正負號整數引數類型。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (4)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:保留 (必須為零)
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
引數值字詞
[0 .. 63]
:64 位元無正負號整數
雙精度浮點引數 (引數類型 = 5)
代表雙精度浮點數。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (5)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:保留 (必須為零)
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
引數值字詞
[0 .. 63]
:雙精度浮點數
字串引數 (引數類型 = 6)
代表字串值。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (6)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 47]
:引數值 (字串參照)[48 .. 63]
:保留 (必須為零)
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
引數值串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
指標引數 (引數類型 = 7)
代表指標值。參照項目的其他相關資訊可透過與相同指標相關聯的使用者空間物件記錄提供。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (7)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:保留 (必須為零)
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
引數值字詞
[0 .. 63]
:指標值
核心物件 ID 引數 (引數類型 = 8)
代表 koid (核心物件 ID)。有關參照的其他資訊,可由與同一個 koid 相關聯的「核心物件記錄」提供。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (8)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:保留 (必須為零)
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊
引數值字詞
[0 .. 63]
:koid (核心物件 ID)
布林值引數 (引數類型 = 9)
代表布林值。
格式
引數標頭字詞
[0 .. 3]
:引數類型 (9)[4 .. 15]
:引數大小 (包含這個字詞) 為 8 個位元組的倍數[16 .. 31]
:引數名稱 (字串參照)[32 .. 63]
:1 位元填充 0
引數名稱串流 (除非字串參照代表內嵌字串)
- UTF-8 字串,填充為 0 到 8 位元組的對齊