診斷資料保留：在重新啟動後儲存檢查結果

診斷持久性是一項服務，可在裝置重新啟動一或多次後，儲存特定檢查資料。如要追蹤失敗狀態、歷來指標或其他必須在重新啟動後繼續運作的遙測資料，請將這項服務設為自動儲存資料。

行為和用途

持久性特別適合用於在下列情況後復原診斷資料：

意外重新啟動：持續性會根據您設定的頻率定期儲存資料，並在裝置重新啟動後繼續運作。
元件當機：儲存值後，系統絕不會捨棄該值。舉例來說，如果元件在第一個樣本中發布資料，但在下一個樣本之前捨棄該資料或當機，則 Persistence 會將原始資料保留在持續性檔案中。

快速入門指南

如要設定「持續性」來儲存元件的檢查資料，請按照下列步驟操作：

找出檢查資料
建立設定檔
估算 max_bytes
更新版本

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 限制：

在裝置上執行元件，並填入要保留的檢查資料。如要進一步瞭解如何填入檢查資料，請參閱「程式碼研究室：使用檢查」。
使用確切的選取器在本機執行 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. 更新版本

將新設定檔新增至 //bundles/assembly/BUILD.gn 的 diagnostics-persistence 套件設定，即可將該檔案新增至建構作業。

找出 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"
+       },
      ]

讀取保留的資料

下次啟動時 (軟體更新檢查完成後)，系統會將儲存的資料重新發布到「檢查」中。

資料由 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` 中這個資料集的專屬 ID。只能使用小寫英文字母和連字號 (例如 `"my-feature-stats"`)。
`service_name`	string	相關標記的分組 ID。只能使用小寫英文字母和連字號 (例如 `"my-service"`)。
`selectors`	[]string	要擷取及儲存的確切 `INSPECT:` 選取器清單。
`max_bytes`	整數	擷取的檢查酬載大小上限 (以位元組為單位)。如果取樣資料超過這個上限，系統會以錯誤字串取代儲存的資料。
`min_seconds_between_fetch`	整數	Archivist 應取樣這些選取器的頻率。
`persist_across_boot`	布林值 (預設為 `false`)	如果 `true`，系統不會在下次啟動時清除已儲存的資料，且會繼續累積歷來啟動資料。

隱私權注意事項

持續性是強大的偵錯工具，但若使用不當，也可能造成隱私權風險。

跨啟動連結：啟用 persist_across_boot 可保留啟動間的已儲存資料，累積歷來資料。這會建立裝置使用情況的長期記錄，可用於追蹤多次啟動的使用者。這也可能違反其他隱私權保護措施，例如在限時的匿名 ID 中，對裝置或使用者進行數位指紋採集。
資料保留：持續性資料會儲存在裝置上，任何可實際存取裝置的人都能存取這些資料。請務必考量您要保存的資料是否屬於機密資訊，以及是否應採取額外安全措施加以保護。
資料最小化原則：只保留偵錯元件所需的資料。避免保留不必要的資料，因為這可能會增加隱私權風險。

常見問題

Persistence 是否適用於延遲節點？

可以。持續性提供內建支援，可檢查 Lazy Nodes。持續性會向 Archivist 註冊必要的選取器和擷取頻率。在每個間隔，Archivist 會主動查詢元件的選取器，這會觸發任何 Lazy Node 的評估，讓系統儲存動態產生的資料。