概览
Fuchsia 中的诊断平台包含多项服务。其中每项服务(例如数据渗漏、指标轮询和错误状态分析)都有一个共同的需求,需要描述其诊断数据的特定属性。
我们创建了一个称为“诊断选择器”的域特定语言 (DSL),它能够描述组件公开的诊断属性。选择器旨在对诊断架构执行操作,并用于以下情形:
- 诊断数据以“数据层次结构”编码,其中已命名节点同时托管子节点和已命名的诊断属性。
- 诊断层次结构取决于公开数据的特定组件(按名称)。
诊断选择器具有以下高级语法:
<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
此组件选择器根据其祖父级 core
明确标识名为 foo
的组件。
组件选择器的每个段(以正斜杠分隔的各个部分)恰好描述了组件拓扑的一个“级别”。
组件选择器细分只能包含组件名称中可接受的字符。每个组件选择器细分都是一个实例名称或带有实例名称的集合名称,后者具有一组受限的允许字符和长度。集合名称和实例名称之间的冒号 :
必须使用反斜杠 (\
) 进行转义。
通配符
组件选择器支持通配符,这样将匹配组件选择器的单个“级别”。请考虑以下应用于以上示例拓扑的 module_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 编码。在本例中,层次结构来自“Inspect”。
"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
,但如果存在更多连接节点,它们也会匹配。
媒体资源选择器
语法
属性选择器是所有子选择器中最简单的元素。它会定义与单个字符串匹配的模式,该字符串是诊断层次结构中的属性名称。诊断层次结构中的所有属性都具有字符串名称。省略属性选择器实际上相当于层次结构路径选择器
与前面的选择器段一样,如果您要匹配星号 (*
)、正斜杠 (/
)、反斜杠 (\
)、空格(制表符 \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.
完整的选择器示例
以下选择器将从系统上存在于 realm1
下的任何领域中的任何 echo.cm
实例中。检索到的数据将是位于 a/b/c
的节点上的 active_connections
属性。
realm1/*/echo:a/b/c:active_connections
以下选择器会从系统上存在于 realm1
直接下的任何领域中的任何 echo.cm
实例中,选择检查数据。检查数据将是位于 a/b/c/d
的节点上的 memory_usage property
。
realm1/echo:a/b/c/d:*