配置分类

分类功能会根据配置文件分析“诊断”数据。

概览

借助分类，任何人都可以轻松添加新方法来分析非标称条件下的 fx snapshot 数据。

默认情况下，配置文件从 //src/diagnostics/config/triage/*.triage 读取。只需在其中添加新的配置文件即可。

配置文件语法为 JSON5。

每个配置文件指定四种配置：选择器和评估（统称为“指标”）、操作和测试。

  • 选择器会加载供评估和操作使用的值。
  • 求值可用于计算供“求值”和“操作”使用的值。
  • 操作决定了如何处理特定指定值。
  • 测试包含示例数据，用于验证指定 Action 是否会正确触发。

每个“选择”“评估”“测试”和“操作”都有一个名称。因此，配置文件的结构如下：

{
    "select": {
        "select1": "type:component:node/path:property",
        "select2": "type:component:node/path:property"
    },
    "eval": {
        "name1": "select1+select2",
        "name2": "select1 - select2"
    },
    "act": {
        "action1": { .... },
        "action2": { .... }
    },
    "test": {
        "test1": { .... },
        "test2": { .... }
    }
}

名称和命名空间

选择、评估、操作、测试和配置文件名称由一个小写字母或下划线字符组成，后跟零个或多个字母数字或下划线字符。因此，“abc123”和“_abc_123”是有效名称，但“123abc”“a.b.c”和“abc-123”不是有效名称。需要特别注意的是，文件名不得包含英文句点（.triage 扩展名除外）。

一个文件中的评估、测试和操作可以引用另一个文件中的选择器、评估和操作。文件基名用作命名空间。:: 用作分隔符。例如，如果加载了文件 foo.triage，且该文件包含名为 bar 的指标，则任何配置文件都可能引用 foo::bar。

名称可以在指标、测试和操作之间重复使用，但不能在“选择”和“评估”之间重复使用。

用户定义的名称必须以小写字母开头。语言提供的函数以大写字母开头。

注意：我们不保证该程序的当前版本会强制执行这些限制。

选择器

选择器使用选择器格式。第一个 : 前面的文本会从 inspect.json 文件中选择组件名称。以 . 分隔的中间部分指定“检查节点名称”，它们构成了以第二个 : 命名的媒体资源的路径。

计算

求值字符串是采用普通运算符优先级的中附加数学表达式。

()。

算术运算符为 + - * / // /? //?。/ 是浮点除法；// 是整数除法。? 的除法运算符返回问题：：除数为 0 时忽略。

函数是函数名称 '(', 逗号分隔表达式列表, ')。提供的函数包括：

  • 布尔值
    • And(1+ args)
    • Or(1+ args)
    • Not(1 arg)
    • 如果值为 Missing 类型的错误指示，则 Missing(value) 会返回 true。
    • 如果值为任何类型的错误，Problem(value) 会返回 true。
    • True() 返回 true
    • False() 返回 false
  • 数字
    • Min(1+ args)
    • Max(1+ args)
    • Abs(1 arg)
  • 功能
    • Fn([name1, name2, ...], expression)
    • Map(function, vector1, vector2, ...)
    • Fold(function, vector, optional_start_value)
    • Filter(function, vector)
    • Apply(function, [arg1, arg2, ...])
    • Count(vector)
  • 时间
    • Days()、Hours()、Minutes()、Seconds()、Millis()、Micros() 和 Nanos() 会计算与单调时间戳进行比较的值。
    • Now() 会返回创建诊断数据的大致时间戳。
  • 其他
    • Option(value1, value2, value3...) 会返回第一个有用值以支持选择器迁移和默认值：第一个非空列表、非 Missing 值（如果有）或空列表（如果已提供）；或者缺失。
    • Annotation(string) 会从 annotation.json 文件（如果存在）中提取相应的键。
    • 如果 syslog、内核日志或先前启动日志包含与正则表达式匹配的行，则 SyslogHas(regex)、KlogHas(regex)、BootlogHas(regex) 会返回 true。
    • StringMatches(value, regex) 会将指定的正则表达式应用于指定值，如果存在匹配项，则返回 true。Rust 正则表达式 crate 支持正则表达式语法。

指标类型遵循从检查文件中读取的类型。目前，UInt 会在读取时转换为 Int。对混合 Int 和 Float 进行操作会将结果提升为浮点数。

布尔运算为 > < >= <= == !=。等式测试 == 和 != 会比较数字、布尔值、字符串和矢量。> < >= <= 仅比较数字。

空格在任何位置都是可选的，但建议在 infix 运算符中使用空格。

指标名称（包括命名空间型名称）无需进行特殊分隔。

函数编程和矢量

实际上，每个选择器都会返回一个向量，但是单项向量会自动解封，以便进行算术和布尔值计算。除非同一名称在 check.json 中多次出现，否则不含通配符的选择器会返回单项矢量。

带有通配符的选择器、bootstrap/driver_manager 和 core/network/netstack 的选择器，以及（最终）日志上的选择器，可以在向量中返回多个项。为了处理这些值，Triage 提供了以下函数：

  • Fn(parameters, 表达式) - 例如 Fn([a, b], a+b)
  • Map(function, vector1, vector2...)
  • Fold(function, vector) 或 Fold(function, vector, start_value)
  • Filter(函数, 矢量)
  • 计数（向量）

值的矢量写为 [ expr, expr, expr ]。

如果 Map 的 values 参数不是矢量，则其值会应用于每次迭代。如果所有 values 都不是矢量，或未提供 values，则返回空矢量。如果矢量 values 具有不同的长度，则最短的那一个会确定结果长度，不使用其余值。

Count() 不会检查矢量 values 中项目的类型。非矢量 values 的 Count() 会返回 Missing。

如果 Fn 表达式是“eval”表达式的完整内容，则该表达式的名称可用作映射、折叠或过滤器的第一个参数。

如果某个函数的参数存在错误，则传递给该函数的函数会返回 Missing。如果函数的求值失败（例如由于类型不当），则传递给该函数的函数可能会返回部分值：

  • 地图会返回一个矢量，其中某些元素可能缺失。
  • Fold 返回 Missing。
  • 过滤器预期其过滤器函数返回布尔值 true 或 false。如果该函数返回任何其他结果（包括 Missing），Filter 会在其结果列表中的该点处添加一个 Missing 值。

操作

每个 Action 都决定了如何显示指定选择器的信息。目前有两种操作：“警告”和“采样平均值”。您可以通过为 type 字段提供适当的值来指定操作。

警告类型

Warning 是一种操作，用于在满足布尔条件时发出提醒。

Warning 支持以下字段：

  • trigger 是必填字段，用于指定提供布尔值的指标的名称。
  • print 是必填字段，用于指定收到警告时要输出的字符串。
  • tag 是一个可选字段，用于将代码与此 Action 相关联。
  • file_bug（可选字符串字段）指定应提交 bug 以及提交位置。分类不会直接提交 bug；此字段只是通知使用者（真人用户或自动化流水线）。该资源可以是问题跟踪器组件（例如“Fuchsia > Internationalization (i18n)”），或对消费者理解的其他问题跟踪器的引用。
    "actions": {
        "disk_usage_high": {
            "type": "Warning", "trigger": "disk_used / disk_total > 0.95", "print": "Disk usage is high!"
        }
    }

量具类型

Gauge 是调用分类时特定值的快照。Gauge 支持以下字段：

  • value 是必填字段，用于指定要显示的值。
  • format 为可选字段，用于指定刻度盘值的格式规则。

格式

format 字段允许用户控制刻度盘值的显示方式。如果未提供此字段或者指定的值无效，值将按原样显示。format 支持以下值：

  • percentage：以百分比值的形式输出浮点数。
    "actions": {
        "disk_usage": {
            "type": "Gauge", "value": "disk_used / disk_total", "format": "percentage"
        }
    }

测试

每项测试都会指定：

  • 示例数据，由 inspect 进行键控
  • 根据该数据应触发的操作列表，由 yes 键控
  • 在指定数据的情况下不应触发的操作列表，由 no 键控

示例数据与 check.json 文件的格式相同：映射数组，其中每个地图都包含 path 和 contents 字段。

    "tests": {
        "test1": {
            "yes": ["action1", "action2"],
            "no": ["action3"],
            "inspect": [
                {
                    "path": "global_data",
                    "contents": {"root": {"stats":
                        {"total_bytes": 10, "used_bytes": 9}}}
                }
            ]
        }
    }