此页面由 Cloud Translation API 翻译。

对结构化记录进行编码

Fuchsia 使用线格格式来记录结构化日志，此格式受到其轨迹格式的启发。这种传输格式允许将任意数据结构作为日志记录进行使用和传播。

验证

日志记录的大小上限为 32kb。

如果写入程序向诊断服务发送超大或无效记录，则其数据流会关闭，诊断服务会记录错误。

基元

整数采用小端序编码。有符号整数是二进制补码。

时间戳是有符号的 64 位整数，以纳秒为单位，由 zx_clock_get_monotonic 记录。

字符串由 16 位“字符串引用”表示。如果最高有效位 (MSB) 为 0，则字符串为空。如果 MSB 为 1，则引用的剩余位表示后续 UTF-8 字节流的长度。MSB 为 0（空字符串除外）的所有字符串引用均预留用于未来的扩展。系统会用零填充字符串，直到字符串对齐到 8 字节。

记录由多个 8 字节的字组组成，并且按 8 字节对齐。

日志记录必需的元数据包括记录类型、记录的总长度和时间戳。它们在记录的前 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（类型）	name
`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

对“legacy”格式的消息进行编码

调用 LogSink.Connect 的组件应在“数据报”模式下传递套接字（与“流式传输”相反），并将“旧版”有线格式写入其中。它使用小端整数以及带长度前缀和以 null 结尾的 UTF-8 字符串的组合。

目前，只有 Go 日志记录器实现会使用此方法。