诊断持久性：在重新启动后保存检查结果

诊断持久性是一项服务，可在设备上存储特定的检查数据，即使设备重启一次或多次，这些数据也不会丢失。如果您需要跟踪失败状态、历史指标或其他必须在重启后继续留存的遥测数据，请将此服务配置为自动保存数据。

行为和使用场景

持久性对于在以下情况后恢复诊断数据特别有用：

意外重启：持久性会根据您配置的频次定期保存数据，并在设备重启后继续保留数据。
组件崩溃：一旦保存，持久性永远不会丢弃值。例如，如果您的组件在第一个样本中发布数据，但在下一个样本之前丢弃该数据或崩溃，则持久性会在持久性文件中保留原始数据。

快速入门指南

如需配置持久性以保存组件的“检查”数据，请按照下列步骤操作：

确定检查数据
创建配置文件
估算值 max_bytes
更新 build

1. 确定您的检查数据

选择您需要保存的特定数据。您需要组件数据的确切 INSPECT: 选择器（例如，INSPECT:core/pkg-resolver:root/resolver_service/active_package_resolves:*）。

2. 创建配置文件

在 //src/diagnostics/config/persistence 或 //vendor/*/diagnostics/config/persistence 中创建一个新的 .persist 文件。

该文件使用 JSON5。为要保留的数据定义参数：

[
  {
    tag: "cache-fallbacks", // Unique name
    service_name: "pkg-resolver", // Grouping for tags
    max_bytes: 500, // Max size of the persisted data
    min_seconds_between_fetch: 3600, // How frequently to sample the data
    selectors: [
      "INSPECT:core/pkg-resolver:root/resolver_service:cache_fallbacks_due_to_not_found",
      "INSPECT:core/pkg-resolver:root/resolver_service/active_package_resolves:*",
    ],
  },
]

3. 估算值 `max_bytes`

系统会在运行时强制执行持久性数据的大小。如果选择器提取的数据量超过 max_bytes，系统会永久舍弃此标记的所有已保存数据，并将其替换为单个错误字符串。

如需估算正确的 max_bytes 限制，请执行以下操作：

在设备上运行组件，并填充您希望保留的检查数据。如需详细了解如何填充检查数据，请参阅 Codelab：使用检查。
在本地运行 ffx inspect show 并使用确切的选择器，然后通过 jq 管道传输输出，以剥离未持久保存的数据。最后，使用 wc -c 统计字节数。例如：

ffx --machine json inspect show \
    'core/pkg-resolver:root/resolver_service:cache_fallbacks_due_to_not_found' \
    'core/pkg-resolver:root/resolver_service/active_package_resolves:*' \
    | jq -c '.[] | pick(.moniker, .payload.root)' \
    | wc -c

添加充足的缓冲时间（例如，20-50%）添加到此总和中，以考虑字符串长度变化、未来字段添加和 JSON 格式设置开销。

4. 更新 build

通过将新配置文件添加到 //bundles/assembly/BUILD.gn 中的 diagnostics-persistence 软件包配置，将该文件添加到 build 中。

找到 package_name = "diagnostics-persistence" 代码块，并将 .persist 文件添加到 files 列表：

      package_name = "diagnostics-persistence"
      files = [
        {
          source = "//src/diagnostics/config/persistence/netstack.persist"
          destination = "netstack.persist"
        },
+       {
+         source = "//src/sys/pkg/bin/pkg-resolver/pkg-resolver.persist"
+         destination = "pkg-resolver.persist"
+       },
      ]

读取持久性数据

在下一次启动时（软件更新检查完成后），保存的数据会重新发布到 Inspect 中。

数据由 diagnostics-persistence 组件托管。原始路径会添加您配置的 service_name 和 tag 作为前缀。

$ ffx inspect show core/diagnostics/persistence
core/diagnostics/persistence:
  root:
    persist:
      pkg-resolver:
        cache-fallbacks:
          core/pkg-resolver:
            resolver_service:
              cache_fallbacks_due_to_not_found: 2

配置参考文档

.persist JSON5 文件格式需要一个对象数组，其中每个对象都定义了一个持久性标记。每个标记都接受以下字段：

字段	类型	说明
`tag`	string	相应数据集合在 `service_name` 中的唯一标识符。只能包含小写字母和连字符（例如，`"my-feature-stats"`）。
`service_name`	string	相关代码的分组标识符。只能包含小写字母和连字符（例如，`"my-service"`）。
`selectors`	[]string	要收集和保存的确切 `INSPECT:` 选择器的列表。
`max_bytes`	整数	提取的检查载荷允许的最大大小（以字节为单位）。如果抽样数据超出此限制，系统会将保存的数据替换为错误字符串。
`min_seconds_between_fetch`	整数	Archivist 应以多高的频率对这些选择器进行抽样。
`persist_across_boot`	布尔值（默认值为 `false`）	如果值为 `true`，则保存的数据不会在下次启动时清除，并且会继续累积历史启动数据。

隐私注意事项

持久性是强大的调试工具，但如果不谨慎使用，也可能会带来隐私风险。

跨启动关联：启用 persist_across_boot 可在启动时保留已保存的数据，从而积累历史数据。这会创建设备使用情况的长期记录，可用于在多次启动时跟踪用户。这还可能违反其他隐私保护措施，例如通过限时匿名 ID 对设备或用户进行指纹识别。
数据保留：持久性数据存储在设备上，任何能实际访问设备的人都可以访问这些数据。请务必考虑您要持久保存的数据的敏感程度，以及是否应通过额外的安全措施来保护这些数据。
数据最小化：仅持久保存调试组件所需的数据。避免持久保存不必要的数据，因为这会增加隐私风险。

常见问题解答

持久性是否适用于延迟节点？

可以。持久性提供对检查延迟节点的内置支持。持久性向 Archivist 注册其所需的选择器和提取频率。在每个时间间隔，归档器都会主动查询组件的选择器，这会触发对任何延迟节点的评估，从而使系统能够保存其动态生成的数据。