為結構化記錄編碼

Fuchsia 會使用結構化記錄的線路格式,靈感來自於 追蹤格式。這種傳輸格式可讓任意資料結構以記錄的形式傳輸及傳播。

驗證

記錄記錄的大小上限為 32 KB。

如果寫入器傳送過大或無效的記錄給診斷服務,系統會關閉串流,並由診斷服務記錄錯誤。

基本

整數採用小端序編碼。帶正負號的整數是二補數。

時間戳記是帶正負號的 64 位元整數,以奈秒為單位,由 zx_clock_get_monotonic 記錄。

字串以 16 位元的「字串參照」表示。如果最高有效位元 (MSB) 為 0,字串會是空白。如果 MSB 為 1,ref 的其餘位元會指出後續 UTF-8 位元組串流的長度。除了空字串以外,MSB 為 0 的所有字串參照都保留供日後擴充。字串會以零填充,直到對齊 8 位元組為止。

記錄由多個 8 位元組字詞組成,且會對齊 8 位元組。

記錄的必要中繼資料包括記錄類型、記錄總長度和時間戳記。這些資訊會編碼到記錄的前 16 個位元組:

注意:

  • 「大小字詞」欄位包含標題字詞。
  • 時間戳記以奈秒為單位。

目前所有記錄都應具有 type=9。這是為了反映追蹤格式而選擇的格式,但可能需要變更,追蹤工具才能處理這些記錄。嚴重程度的值定義於 /sdk/fidl/fuchsia.diagnostics/severity.fidl

引數

記錄記錄資料會透過型別鍵/值組合清單傳送。索引鍵一律為非空白字串,支援不同類型的引數,而值則可有多種型別。

引數標頭

每個引數都有 8 位元組的標頭,後面依序是引數名稱和引數值。在寫入引數內容之前,名稱會以零填補,達到 8 位元組對齊。

注意:

  • 「大小字詞」欄位包含標題字詞。
  • 「名稱參照」是引數名稱的字串參照。
  • 「varies」部分會因引數類型而異,如果未使用,則必須為 0。
  • 「名稱長度」為「64 * nameref」。
  • 「name」是引數的名稱,總長度 (不在圖表中) 為 namelen,並填補至 8 位元組對齊。

引數標頭的前 4 個位元會決定引數的類型:

T (類型) name
3 帶正負號的 64 位元整數
4 不帶正負號的 64 位元整數
5 雙精度浮點數
6 UTF-8 字串
9 布林值

帶正負號的 64 位元整數引數

引數名稱終止後,會附加帶正負號的整數。

不帶正負號的 64 位元整數引數

無符號整數會附加在引數名稱終止後。

64 位元浮點引數

浮點數會附加在引數名稱終止後。

字串引數

字串會以 UTF-8 編碼,並以零填補至 8 位元組對齊,然後附加在引數名稱後方。

布林值引數

布林值會附加在引數標頭的 NameRef 欄位之後。

編碼「舊版」格式訊息

呼叫 LogSink.Connect 的元件應以「資料報」模式 (而非「串流」模式) 傳遞通訊端,並將「舊版」線路格式寫入其中。這會使用小端整數,以及以長度為前置字元和以空值結尾的 UTF-8 字串。

目前只有 Go 記錄器實作項目會使用這項功能。