fuchsia.diagnostics

添加次数：7

协议

ArchiveAccessor

在 fuchsia.diagnostics/read.fidl 中定义

用于与不同诊断数据源交互的外部协议。

添加日期：18

StreamDiagnostics

针对系统上的诊断数据创建迭代器。

  • 通过在 SNAPSHOT 模式下进行流式传输（仅提供系统上的当前状态的诊断数据），迭代器可能是有限的。
  • 通过在 SNAPSHOT_ THEN_Subscriptions 或 Subscribe 模式下进行流式传输，迭代器可以是无限的；前一个模型会针对系统的当前状态提供迭代，然后都针对新到达的诊断数据提供持续迭代。

  • 向 result stream 请求 [fuchsia.diagnostics/BatchIterator]，诊断记录会通过此方式向客户端公开。

    • 墓碑：
      • INVALID_ARGS：StreamParameters 结构中缺少必需的参数。
      • WRONG_TYPE：StreamParameters 结构体提供的选择器格式不正确。

  • 请求 stream_parameters 是一个 [fuchsia.diagnostics/StreamParameter]，用于指定如何配置数据流。

请求

名称类型
stream_parameters StreamParameters
result_stream server_end<BatchIterator>

BatchIterator

在 fuchsia.diagnostics/read.fidl 中定义

从概念上讲，它是指目录迭代器，其中迭代器中的每个元素都是一个可以与其他结果串联的完整文件。

添加日期：18

GetNext

返回 [fuchsia.diagnostics/FormattedContent] 结构体的矢量，其格式由提供给生成此 BatchIterator 的 Reader 协议的 format_settings 参数指定。

空向量表示数据层次结构已完全迭代，后续 GetNext 调用将始终返回空向量。

当 BatchIterator 通过订阅模型提供结果时，对 GetNext 的调用将挂起，直到有新数据可用为止，它不会返回空矢量。

  • 会返回 FormattedContent 结构体的向量。连接到一个批次的客户端应调用 GetNext()，直到返回空矢量（表示已读取整个数据层次结构）。
  • 错误 [fuchsia.diagnostics/ReaderError] 值，表示读取底层数据层次结构或对这些层次结构进行格式设置以填充 batch 时出现问题。请注意，这些问题不包括单个组件的数据层次结构无法读取。 迭代器可以容忍个别组件数据源无法读取，无论该失败是超时还是格式不正确的二进制文件。如果 GetNext 调用失败，该子集的数据层次结构结果将会被丢弃，但之后对 GetNext 的调用将提供 FormattedDataHierarchies 的新子集。

请求

<EMPTY>

响应

名称类型
payload BatchIterator_GetNext_Result

WaitForReady

表示 BatchIterator 已连接。如果 BatchIterator 尚未连接，此方法将挂起，直到连接成功。

请求

<EMPTY>

响应

名称类型
payload BatchIterator_WaitForReady_Result

LogSettings

在 fuchsia.diagnostics/log_settings.fidl 中定义

此协议允许客户端修改系统中组件的日志记录行为。

RegisterInterest

已移除：18 已弃用：12

请求

名称类型
selectors vector<LogInterestSelector>[64]

SetInterest

请求更改匹配组件的兴趣。

每个组成部分都包含一组请求的兴趣。

收到对 LogSettings#SetInterest 的新请求时，匹配的组件集会收到新的最低兴趣。如果利息低于之前的最低利息，则系统会发送包含新的最低利息的 SetInterest 请求。

如果与 LogSettings 的连接发送了另一个 SetInterest 请求，则其先前的兴趣请求将被撤消。

当与 LogSettings 的连接完成时，兴趣会被撤消。每个匹配的组成部分最低兴趣度都会更新为集合中新的最低兴趣度。

添加数量：12

请求

名称类型
selectors vector<LogInterestSelector>[64]

响应

<EMPTY>

结构

BatchIterator_GetNext_Response 资源

在 fuchsia.diagnostics/reader.fidl 中定义

字段类型说明默认
batch vector<FormattedContent>[64] 无默认取景方式

BatchIterator_WaitForReady_Response

在 fuchsia.diagnostics/reader.fidl 中定义

<EMPTY>

LogInterestSelector

在 fuchsia.diagnostics/log_settings.fidl 中定义

指定兴趣及其指定目标

字段类型说明默认
selector ComponentSelector

与要请求兴趣的组成部分相匹配。

 无默认取景方式
interest Interest

将发送到与选择器匹配的组件的兴趣级别。

 无默认取景方式

PropertySelector

在 fuchsia.diagnostics/selector.fidl 中定义

选择器，用于定义要匹配的一组节点，并在这些匹配的节点上，定义一组要匹配的命名属性。

字段类型说明默认
node_path vector<StringSelector>[100]

StringSelector 的矢量，充当经过命名节点层次结构的路径的模式匹配器。矢量中的每个条目都是数据层次结构中单个命名节点的选择器。然后，命名节点的选择器矢量会在数据层次结构中的路径上定义选择器。

节点路径支持通配符，这会对节点层次结构中的单个级别进行全局搜索。例如：root/a/b//d 将匹配位于节点 b 的某个子节点之后的所有名为 d 的节点。root/a/b/c 将匹配 b 下以字符“c”开头的所有节点。

 无默认取景方式
target_properties StringSelector

一个 StringSelector，充当数据层次结构中节点上字符串命名的属性的模式匹配器。

target_properties 支持通配符，将与 node_path 匹配的任何节点上的所有属性进行匹配。

 无默认取景方式

SubtreeSelector

在 fuchsia.diagnostics/selector.fidl 中定义

用于定义要匹配的一组节点的选择器，系统会为其选择包括这些节点的整个子树。

字段类型说明默认
node_path vector<StringSelector>[100]

StringSelector 的矢量，充当经过命名节点层次结构的路径的模式匹配器。矢量中的每个条目都是数据层次结构中单个命名节点的选择器。然后，命名节点的选择器矢量会在数据层次结构中的路径上定义选择器。

节点路径支持通配符，这会对节点层次结构中的单个级别进行全局搜索。例如：root/a/b//d 将匹配位于节点 b 的某个子节点之后的所有名为 d 的节点。root/a/b/c 将匹配 b 下以字符“c”开头的所有节点。

 无默认取景方式

枚举

数据类型严格

类型：uint8

在 fuchsia.diagnostics/reader.fidl 中定义

名称值说明
1

在系统上完成检查层次结构。
3

系统中的日志流。

格式严格

类型：uint32

在 fuchsia.diagnostics/format.fidl 中定义

用于指定 Reader 结果的输出格式的枚举。

名称值说明
1

根据 Diagnostics Json 架构规范转储读取结果。
2

根据 Iquery 文本规范转储读取结果。
3

根据诊断 CBOR 架构规范转储读取结果。

添加了：HEAD

ReaderError 严格

类型：uint32

在 fuchsia.diagnostics/read.fidl 中定义

描述通过结果迭代器向客户端提供结果时流式传输协议的潜在故障状态的枚举。

名称值说明
1

严重级别严格

类型：uint8

在 fuchsia.diagnostics/severity.fidl 中定义

给定记录的严重性。

名称值说明
16

跟踪记录包含有关程序执行的详细信息。
32

调试记录包含面向开发者的程序执行信息。
48

信息记录包含有关程序执行的一般信息。（默认）
64

警告记录包含有关潜在问题操作的信息。
80

错误记录包含失败操作的相关信息。
96

严重记录用于传递有关导致程序终止的操作的信息。

StreamMode 严格

类型：uint8

在 fuchsia.diagnostics/read.fidl 中定义

枚举指定用户可以连接到哪些模式并流式传输诊断指标。

名称值说明
1

该数据流将在连接时提供诊断数据的快照，然后结束。
2

该数据流将在连接时提供诊断数据的快照，然后对数据流的后续调用将挂起，直到有新的诊断数据可用。
3

在系统提供新的诊断数据之前，对音频流的调用将会挂起。在调用数据流之间，系统会缓冲新到达的数据。

表

ComponentSelector

在 fuchsia.diagnostics/selector.fidl 中定义

指定组件名称模式，用于标识为组件选择的组件。

组件选择器支持通配符，这会 glob 组件名称的单个“级别”。例如：core//echo 将匹配仅在核心下运行的所有 echo 实例，但没有进一步嵌套的 echo 实例。

组件选择器还支持递归通配符，该通配符将标记组件名称的多个“级别”。例如：core/* 会匹配在 core/ 下运行的所有组件实例及其所有后代。请注意，通配符不会选择核心本身。如果客户端希望选择包含根的子树，则应传递两个选择器，例如：core core/** 递归通配符只能作为选择器的最后一段。

序数字段类型说明
moniker_segments vector<StringSelector>[25]

对要选择的组件名称的模式进行矢量编码。这些名称是相对于档案者所知道的“根”层级结构的子名称。

必须至少提供一个 StringSelector，用于指定与当前选择器匹配的组件名称。

兴趣

在 fuchsia.diagnostics/interest.fidl 中定义

“兴趣”表示客户端所需的诊断数据的范围，例如用于过滤消息或控制其生成。

序数字段类型说明
min_severity Severity

所需的最低严重级别。组件应包含严重级别不低于此严重级别的记录。

如果不存在，则解读为 Severity.INFO。

PerformanceConfiguration

在 fuchsia.diagnostics/read.fidl 中定义

用于配置诊断数据流性能属性的参数。

序数字段类型说明

1

 max_aggregate_content_size_bytes uint64

诊断数据流的批处理迭代器返回的所有格式化内容的最大汇总大小。如果为在订阅模式下配置的流设置此值，则流会在达到大小上限时终止。注意：可选
batch_retrieval_timeout_seconds int64

用于指定等待单个组件“提取”其诊断数据的最大秒数的配置。此值可用于测试，或者如果您知道自己感兴趣的组件在高负载下情况，则可以使用此值。 如果未提供，将使用 https://fuchsia.googlesource.com/fuchsia/+/refs/heads/master/src/diagnostics/archivist/src/Constants.rs 中定义的 PER_COMPONENT_ASYNC_TIMEOUT_SECONDS。 注意：可选

选择器

在 fuchsia.diagnostics/selector.fidl 中定义

结构化选择器，其中包含在数据层次结构中的节点拥有的以字符串命名的属性中进行模式匹配所需的所有信息，其中数据层次结构属于特定组件。

这些选择器以文本形式表示为三段（以英文冒号分隔），具体指定： <component_moniker>:<node_selector>:<property_selector> 示例： 属性选择： realm1/realm2/echo:root/active_users:user_count

Subtree selection:
     realm1/realm2/echo:root/active_users

序数字段类型说明
component_selector ComponentSelector

用于定义要匹配的组件名称模式的选择器。
tree_selector TreeSelector

选择器，用于定义要在通过 component_selector 匹配的组件所拥有的数据层次结构中进行匹配的数据层次结构属性。

StreamParameters

在 fuchsia.diagnostics/read.fidl 中定义

配置诊断信息流所需的参数。

序数字段类型说明
data_type DataType

[fuchsia.diagnostics/DataType]，用于指定要流式传输到客户端的诊断数据类型。注意：必填
stream_mode StreamMode

一个 [fuchsia.diagnostics/StreamMode]，用于指定流式传输服务器如何提供流式传输的结果。注意：必填
format Format

[fuchsia.diagnostics/Format]，用于指定如何设置返回的诊断数据的格式。 注意：必填
client_selector_configuration ClientSelectorConfiguration

用于指定客户端希望从其连接返回哪些结果的配置。客户端可以使用提供的选择器向量来请求特定的数据子集，也可以指定他们需要所有可用数据。注意：必填
batch_retrieval_timeout_seconds int64

用于指定等待单个组件“提取”其诊断数据的最大秒数的配置。此值可用于测试，或者如果您知道自己感兴趣的组件在高负载下情况，则可以使用此值。 如果未提供，将使用 https://fuchsia.googlesource.com/fuchsia/+/refs/heads/master/src/diagnostics/archivist/src/Constants.rs 中定义的 PER_COMPONENT_ASYNC_TIMEOUT_SECONDS。 注意：可选
performance_configuration PerformanceConfiguration

用于配置诊断流性能属性的参数。 注意：可选

联合

BatchIterator_GetNext_Result 严格 资源

在 fuchsia.diagnostics/read.fidl 中定义

序数变体类型说明
response BatchIterator_GetNext_Response
err ReaderError
framework_err internal

BatchIterator_WaitForReady_Result 严格

在 fuchsia.diagnostics/read.fidl 中定义

序数变体类型说明
response BatchIterator_WaitForReady_Response
framework_err internal

ClientSelectorConfiguration 灵活

在 fuchsia.diagnostics/read.fidl 中定义

序数变体类型说明
selectors vector<SelectorArgument>

[fuchsia.diagnostics/SelectorArgument] 的矢量，用于提供额外的过滤条件来限定数据流的范围。空矢量会被视为配置错误，并会导致 epitaph 信号指示不正确的参数。
select_all bool

如果设置了 select_all，则 select_all 必须为 true，并指定客户端想要检索其连接能够公开的所有数据。

FormattedContent 灵活 资源

在 fuchsia.diagnostics/read.fidl 中定义

包含结构化诊断数据的完整层次结构的保真联合体，可单独将内容解析为文件。

序数变体类型说明
json fuchsia.mem/Buffer

编码为 JSON 的诊断架构。 VMO 最多可包含 1 MB 的诊断数据。
text fuchsia.mem/Buffer

编码为文本的诊断架构。 VMO 最多可包含 1 MB 的诊断数据。
cbor handle<vmo>

编码为 cbor 的诊断架构。 VMO 最多可包含 1 MB 的诊断数据。其大小为 ZX_PROP_VMO_CONTENT_SIZE。

添加了：HEAD

SelectorArgument 灵活

在 fuchsia.diagnostics/read.fidl 中定义

用于归档选择器的参数，可以是预解析的 fidl 结构体，也可以是字符串表示法。

序数变体类型说明
structured_selector Selector

定义模式匹配器的选择器，用于选择层次结构中的组件以及按组件作为命名空间的数据层次结构中的属性。
raw_selector string[1024]

表示 [fuchsia.diagnostics/Selector] 的原始字符串。 该选择器定义了一个模式匹配器，用于选择层次结构中的组件以及按组件作为命名空间的数据层次结构中的属性。注意：从 raw_selector 解析的所有 StringSelector 都将在 string_pattern 模式下解释，从而赋予特殊字符的重要性。如需了解详情，请参阅 https://fuchsia.dev/fuchsia-src/reference/diagnostics/selectors

StringSelector 灵活

在 fuchsia.diagnostics/selector.fidl 中定义

StringSelector 是一个联合，定义了描述用于匹配字符串的模式的不同方式。

序数变体类型说明
string_pattern string[100]

这是提供的字符串，用于定义要匹配的模式。解析器会将星号 ()、冒号 (:) 和反斜杠 () 视为特殊字符。

如果您要匹配字面量星号 ()，则必须对这些星号进行转义。如果您想要与字面量反斜杠 () 匹配，则必须对其进行转义。 如果您要匹配字面量冒号 (:)，则必须对其进行转义。

例如：abc 将匹配确切名称为“abc”的任何字符串。 例如：a* 将匹配任何确切名称为“a”的字符串。例如：a* 将匹配任何以“a”开头的字符串。 例如：a* 将匹配任何以“a”开头的字符串。 例如：ab 将匹配任何以“a”开头、以“a”结尾、以 a 结尾、以 a 结尾的任何字符串。例如： b

此外，“*”字面量会被视为特殊序列，只能与组件选择器中的多个级别匹配。如需了解详情，请参阅 |ComponentSelector|。
exact_match string[100]

这是一个提供的字符串，用于定义要匹配的完全匹配字符串。所有字符均不被视为特殊字符，或携带特殊语法。

TreeSelector 灵活

在 fuchsia.diagnostics/selector.fidl 中定义

TreeSelector 表示针对已命名节点层次结构的选择请求，这些节点具有已命名的属性。

序数变体类型说明
subtree_selector SubtreeSelector

用于定义要匹配的一组节点的选择器，系统会为其选择包括这些节点的整个子树。
property_selector PropertySelector

定义要匹配的一组节点的选择器，并在这些匹配节点上定义一组要匹配的已命名属性。

常量

名称值类型说明
MAXIMUM_ENTRIES_PER_BATCH 64 uint16

之所以选择大小为 64，是因为分批中的条目是 VMO 的句柄，并且每条 Fil 消息的句柄数量上限为 64 个。
MAXIMUM_RAW_SELECTOR_LENGTH 1024 uint16

大小限制为 1024 是一个相对较小的大小限制，可以满足我们遇到的大多数规范选择器的要求。
MAX_DATA_HIERARCHY_DEPTH 100 uint16
MAX_LOG_SELECTORS 64 uint8

可以通过监听器指定的 LogInterestSelector 数上限。
MAX_MONIKER_SEGMENTS 25 uint16
MAX_STRING_SELECTOR_LENGTH 100 uint16