為結構化記錄編碼

Fuchsia 正準備改用電匯格式,以依據追蹤記錄格式產生結構化記錄檔。這種新的記錄傳輸格式,允許任意資料結構使用及傳播做為記錄檔記錄。

驗證

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

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

基本

整數具有少量的 endian 編碼。帶號整數可相輔相成。

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

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

記錄由 8 位元組的字詞組成,並對齊 8 位元組的字詞。

記錄

測試編碼器時,我們建議實作者使用 /sdk/fidl/fuchsia.diagnostics.stream/record.fidl 中的 FIDL 繫結做為記錄的「參照」 API。這些類型可以交叉驗證記錄讀取器和寫入者的互通性。

記錄記錄所需的中繼資料包括記錄類型、記錄的總長度和時間戳記。這些記錄會在記錄的前 16 個位元組中經過編碼:

.---------------------------------------------------------------.
|         |1|1|1|1|1|2|2|2|2|2|3|3|3|3|3|4|4|4|4|4|5|5|5|5|5|6|6|
|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|
|---+-----------+-----------------------------------------------|
| T | SizeWords | Reserved                            | Severity|
|---------------------------------------------------------------|
| TimestampNanos                                                |
'---------------------------------------------------------------'

T (type)       = {0,3}    must be 9
SizeWords      = {4,15}   includes header word
Reserved       = {16,55}  must be 0
Severity       = {56,63}  severity of the log record
TimestampNanos = {64,127}

目前所有記錄應為 type=9 類型。您選擇的是複製追蹤記錄格式,但追蹤工具可能需要變更相關設定,才能處理這些記錄。嚴重性的值定義於 /sdk/fidl/fuchsia.diagnostics/severity.fidl

引數

記錄檔資料是透過已輸入的鍵/值組合清單傳輸。這些鍵一律為非空白字串,且支援不同類型的引數,且值可以有幾種類型。

引數標頭

每個引數都有 8 位元組的標頭,後面接著引數名稱,然後是引數的值。在寫入引數內容之前,該名稱會加上零到 8 位元組對齊。

.---------------------------------------------------------------.
|         |1|1|1|1|1|2|2|2|2|2|3|3|3|3|3|4|4|4|4|4|5|5|5|5|5|6|6|
|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|
|---+-----------+-----------------------------------------------|
| T | SizeWords | NameRef     | Varies                          |
|---------------------------------------------------------------|
| Name (1+ words)                                               |
'---------------------------------------------------------------'

T (type)  = {0,3}           see table below
SizeWords = {4,15}          includes header word
NameRef   = {16,31}         string ref for the argument name
Varies    = {32,63}         varies by argument type, must be 0 if unused
NameLen   = 64*NameRef
Name      = {64,64+NameLen} name of the argument, padded to 8-byte alignment

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

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

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

引數名稱終止後,會加上帶號的整數。

.---------------------------------------------------------------.
|         |1|1|1|1|1|2|2|2|2|2|3|3|3|3|3|4|4|4|4|4|5|5|5|5|5|6|6|
|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|
|---+-----------+-----------------------------------------------|
| 3 | SizeWords | NameRef     | Reserved                        |
|---------------------------------------------------------------|
| Name (1+ words)                                               |
'---------------------------------------------------------------'
| Value                                                         |
'---------------------------------------------------------------'

T (type)  = {0,3}                  must be 3
SizeWords = {4,15}                 includes header word
NameRef   = {16,31}                string ref for the argument name
Reserved  = {32,63}                must be 0
NameEnd   = 64+(64*NameRef)
Name      = {64,NameEnd}           name of the argument, padded to 8-byte alignment
Value     = {NameEnd+1,SizeWords*64}

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

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

.---------------------------------------------------------------.
|         |1|1|1|1|1|2|2|2|2|2|3|3|3|3|3|4|4|4|4|4|5|5|5|5|5|6|6|
|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|
|---+-----------+-----------------------------------------------|
| 4 | SizeWords | NameRef     | Reserved                        |
|---------------------------------------------------------------|
| Name (1+ words)                                               |
'---------------------------------------------------------------'
| Value                                                         |
'---------------------------------------------------------------'

T (type)  = {0,3}                  must be 4
SizeWords = {4,15}                 includes header word
NameRef   = {16,31}                string ref for the argument name
Reserved  = {32,63}                must be 0
NameEnd   = 64+(64*NameRef)
Name      = {64,NameEnd}           name of the argument, padded to 8-byte alignment
Value     = {NameEnd+1,SizeWords*64}

64 位元浮點引數

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

.---------------------------------------------------------------.
|         |1|1|1|1|1|2|2|2|2|2|3|3|3|3|3|4|4|4|4|4|5|5|5|5|5|6|6|
|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|
|---+-----------+-----------------------------------------------|
| 5 | SizeWords | NameRef     | Reserved                        |
|---------------------------------------------------------------|
| Name (1+ words)                                               |
'---------------------------------------------------------------'
| Value                                                         |
'---------------------------------------------------------------'

T (type)  = {0,3}                  must be 5
SizeWords = {4,15}                 includes header word
NameRef   = {16,31}                string ref for the argument name
Reserved  = {32,63}                must be 0
NameEnd   = 64+(64*NameRef)
Name      = {64,NameEnd}           name of the argument, padded to 8-byte alignment
Value     = {NameEnd+1,SizeWords*64}

字串引數

字串是以 UTF-8 編碼,會在 8 位元組對齊前填充零,並在引數名稱後方加上。

.---------------------------------------------------------------.
|         |1|1|1|1|1|2|2|2|2|2|3|3|3|3|3|4|4|4|4|4|5|5|5|5|5|6|6|
|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|
|---+-----------+-----------------------------------------------|
| 6 | SizeWords | NameRef     | ValueRef      | Reserved        |
|---------------------------------------------------------------|
| Name (1+ words)                                               |
'---------------------------------------------------------------'
| Value (1+ words)                                              |
'---------------------------------------------------------------'

T (type)  = {0,3}                  must be 6
SizeWords = {4,15}                 includes header word
NameRef   = {16,31}                string ref for the argument name
ValueRef  = {32,47}                string ref for the argument value
Reserved  = {48,63}                must be 0
NameEnd   = 64+(64*NameRef)
Name      = {64,NameEnd}           name of the argument, padded to 8-byte alignment
Value     = {NameEnd+1,SizeWords*64}

布林引數

系統會在引數標頭的 NameRef 欄位後方加上布林值。

.---------------------------------------------------------------.
|         |1|1|1|1|1|2|2|2|2|2|3|3|3|3|3|4|4|4|4|4|5|5|5|5|5|6|6|
|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|4|6|8|0|2|
|---+-----------+-----------------------------------------------|
| 9 | SizeWords | NameRef     |B| Reserved                      |
|---------------------------------------------------------------|
| Name (1+ words)                                               |
'---------------------------------------------------------------'

T (type)      = {0,3}                  must be 9
SizeWords     = {4,15}                 includes header word
NameRef       = {16,31}                string ref for the argument name
B (BoolValue) = {32}                   boolean value
Reserved      = {33,63}                must be 0
NameEnd       = 64+(64*NameRef)
Name          = {64,NameEnd}           name of the argument, padded to 8-byte alignment

編碼「舊版」格式訊息

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