诊断选择器

概览

Fuchsia 中的诊断平台包含多项服务。这些服务（例如 （例如数据渗漏、指标轮询和错误状态分析）共同需要描述 诊断数据的具体属性。

我们已经创建了一种域特定语言 (DSL)，称为诊断选择器， 能够描述组件公开的诊断属性。选择器的用途是 处理诊断架构，并用于以下情况：

  1. 诊断数据在“数据层次结构”中编码，其中命名节点托管这两个子节点 以及命名的诊断属性
  2. 诊断层次结构归因于公开这些数据的特定组件， 和各自的昵称。

诊断选择器具有以下高级语法：

<component_selector>:<hierarchy_path_selector>:<property_selector>

上述语法的三部分用于逐步将 Fuchsia 诊断数据编入索引 资料来源：

  • component_selector：根据提供方的 名称。
  • hierarchy_path_selector：指定（由提供方）公开的数据层次结构中的路径 感兴趣的特定节点
  • property_selector：指定您在 层级结构。

一些基于诊断平台构建的工具（例如 Triage 和 Detect）时，需要使用选择器来区分数据类型。这些工具扩展了 选择器 DSL，并使用一种指定数据类型的额外语法：

INSPECT|LOG|LIFECYCLE:<component_selector>:<hierarchy_path_selector>:<property_selector>

下面将详细介绍语法的各个部分。

另存为文件

评论

诊断选择器可以写入平面目录中的 cfg 文件中。在这些类别中 文件，可以使用 // 来编写评论。例如，

// a comment
core/sessions/foo

core2/session:foo  // inline comment

组件选择器

语法

组件选择器定义了一个模式，该模式描述一个或多个 多个组件。组件选择器是一系列正斜杠 (/) 分隔的字符串，用于描述从根组件到所需组件的路径。

以下组件拓扑用于演示组件选择器语法：

选择器的直观树状表示形式（如下所述）

鉴于此拓扑，请考虑以下组件选择器：

core/sessions/foo

此组件选择器明确标识了名为 foo 的组件 相对于其祖父级 core 的值。

组件选择器的每个部分（由正斜杠分隔的部分） 只能描述组件拓扑的一个“级别”。

组件选择器细分只能包含组件中接受的字符 名称。每个组件选择器细分都是一个 包含实例名称的实例名称或集合名称 包含一组受限制的字符和长度。集合之间的冒号 : 名称和实例名称必须使用反斜杠 (\) 进行转义。

通配符

组件选择器支持通配符，即匹配单个“level”组件的 选择器。请考虑以下应用于上述示例拓扑的 component_selector：

core/other_comp/*

此选择器匹配系统中在名为 other_comp，它本身在父级 core 下运行。它们的称呼如下：

  • core/other_comp/foo
  • core/other_comp/bar

通配符还可用作单个“级别”的 组件选择器。考虑以下组件选择器（相对于上述拓扑） 图：

core/*_comp

这与系统中在名为 core 的父项下运行的所有组件匹配， 以及以 _runner 结尾的名称。这些术语包括：

  • core/some_comp
  • core/other_comp

组件选择器可以以递归通配符 **（匹配所有组件）结尾 指定大区的以下项目：

core/**

这将匹配系统上在 core 或 core 的任何子领域中运行的所有组件。

组件选择器 ** 单独匹配系统上的所有组件。

层次结构路径选择器

语法

层次结构路径选择器定义了一种通过结构化数据描述路径的模式 一个或多个已命名节点此子选择器的语法与 因为它们都通过命名节点树描述路径。唯一 不同的是下面讨论的可选树名称过滤器。

请考虑以下诊断数据层次结构的 JSON 编码。在本示例中，层次结构 来自检查

"root": {
    "reverser_service": {
        "connection-0x0": {
            "request_count": 1,
        },
        connection_validity: {
            "is_valid": true
        },
        "connection_count": 1,
        "connection_validity": "connection_xyz"

    },
    "version": "part1"
}

鉴于此数据层次结构，请考虑以下层次结构路径选择器：

root/reverser_service/connection-0x0

此层次结构路径选择器明确描述了从数据层次结构的根目录开始的路径 数据层次结构中的特定节点。

选择器的每个段（由正斜杠分隔的部分）只描述一个 数据层次结构的层级或节点。层次结构路径选择器细分可以包含任何字符 不过，如果片段需要包含星号 (*)、正斜杠 (/)， 反斜杠 (\)、空格（制表符 \t 或 ）或冒号 (:) 必须进行转义。

请注意，对于层次结构路径选择器（而非组件选择器），请注意， 指定节点共享同名的子节点和属性的情况。考虑使用 以下选择器：

root/reverser_service/connection_validity

此路径层次结构选择器描述了从根到 connection_validity 节点。它与 reverser_service 节点上的 connection_validity 属性， 可以使用媒体资源选择器进行选择： root/reverser_service:connection_validity。

通配符

层次结构路径选择器支持通配符，即匹配单个“级别”组件的 选择器。以下示例将匹配数据层次结构中所有属于 root 下的节点 redirectr_service：

root/reverser_service/*

通配符还可用作单个“级别”的 组件选择器。以下示例将匹配 reverse_service 下以 和connection-。

core/reverser_service/connection-*

在上面的示例中，唯一匹配的节点是 connection-0x0，但如果有更多连接节点， 它们也会匹配

树名称过滤条件

当一个组件发布多个 fucshia.inspect.Tree 协议时，选择器语法会 支持按协议元数据中的 name 值过滤这些树。

假设您在执行检查时 ffx inspect show core/my_component:

core/my_component:
  metadata:
    name = root
    component_url = fuchsia-boot:///my_component#meta/my_component.cm
    timestamp = 70863435581892
  payload:
    root:
      connections:
        connections_closed = 7
core/my_component:
  metadata:
    name = second_tree
    component_url = fuchsia-boot:///my_component#meta/my_component.cm
    timestamp = 70863435581892
  payload:
    root:
      data:
        values = [0, 1, 2]

如果您知道自己需要 root/data:values 属性，则可以使用树名称过滤器来 可避免使用以下语法截取这两个树的开销（省去属性 选择器部分）：

[name=second_tree]root/data

如果您不知道要针对哪种树进行选择，或者您知道要从所有树中选择 则可以使用此层次结构选择器：

[...]root

这相当于列出所有名称：

[name=root, name=second_tree]root

忽略列表目前将被视为等同于 [...]，但这是软过渡。 如果您知道组件会导出多个具有不同名称的树，请首选显式语法。

如果某个组件在发布 Inspect 时未指定名称，则该组件将隐式更改为 root。 此 bug 跟踪的是使省略的名称过滤条件列表等效于 [name=root]。

名称过滤器列表中的值没有字符限制，但 :、* 和空格 必须转义。如果名称中包含 [a-zA-Z0-9-_] 以外的值，则必须将名称加引号。

名称过滤条件区分大小写。

媒体资源选择器

语法

属性选择器是所有子选择器中最简单的。它定义了一个模式，以匹配 单个字符串，即诊断层次结构上的属性名称。诊断中的所有房源 具有字符串名称。省略属性选择器实际上是一种 层次结构路径选择器

与前面的选择器细分一样，如果您想匹配星号 (*)， 正斜杠 (/)、反斜杠 (\)、空格（制表符 \t 或 ）、 或冒号 (:)，必须使用反斜杠 (\) 进行转义。

通配符

通配符可用于匹配整个属性字符串，也可用作字符串补全 glob。

eg: abc will match any string with the exact name "abc".
eg: a\* will match any string with the exact name "a*".
eg: a\\* will match any that starts with exactly "a\".
eg: a* will match any string that starts with "a".
eg: a*b will match any string that starts with a and ends with b.
eg: a*b*c will match any string that starts with a and ends with c, with b in the middle.

完整的选择器示例

以下选择器将从系统上存在的 echo.cm 实例中选择数据 它在 realm1 下的任何领域。检索到的数据将是 active_connections 属性应用于位于 a/b/c 的节点上。

realm1/*/echo:a/b/c:active_connections

以下选择器将从系统上任何 echo.cm 实例中选择检查数据， 存在于本身直接属于 realm1 的任何领域。检查数据将是 位于 a/b/c/d 的节点上的 memory_usage property。

realm1/echo:a/b/c/d:*