指標名稱預期檔案

Fuchsia 的基礎架構效能測試結果報告基礎架構，針對每項效能測試可能產生的指標名稱設置了一套檢查要求。也稱為指標名稱許可清單。這項功能已在 https://fxbug.dev/42056406 中新增。

如果效能測試產生的指標組合與測試的預期檔案中列出的指標不符，測試會在執行時失敗。這表示如果測試變更後產生的指標組合也會變更，則預期檔案必須更新為一致。

對於 fuchsia.git 中的測試，預期檔案位於 src/tests/end_to_end/perf/expected_metric_names/。

所有新的效能測試 (包括所有以 Python 為基礎的效能測試) 都需要預期檔案。

預期優點

  • 預期檔案旨在協助確保指標命名方式保持一致。這些更新應能讓您更輕鬆地審查指標的命名方式，並可透過 OWNERS 檢查功能強制執行審查。

  • 預期檔案應該要能方便測試作者查看其他指標名稱，以便進行比較，因為清單會簽入程式碼集。

  • 預期檔案可讓您更輕鬆地查看特定 CL 產生的指標清單變化情形。可讓開發人員確保 CL 不會意外移除或重新命名指標。

  • 預期檔案可用來檢查新增的指標數量。這很實用，因為增加大量指標可能需要花費一些成本。

  • 預期檔案應可協助您輕鬆確保測試產生的一組指標具有確定性。指標可以動態產生，並且有多種產生方式。這表示在沒有預期條件檢查的情況下，測試的一組指標可能會不具確定性。這並不理想，因為這樣會導致持續整合建構作業產生的資料出現隨機落差。

如何更新預期檔案

如要更新測試的預期檔案，其中一種方法是使用 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR 環境變數組合，在本機執行測試，如下所示：

FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR=$(pwd)/src/tests/end_to_end/perf/expected_metric_names/ \
    fx test --e2e -o host_x64/fidlc_microbenchmarks_test

設定這個環境變數後，測試就會將更新後的預期檔案寫入環境變數指定的目錄。請注意，這不會在預期檔案中保留選用指標名稱。

如未設定這個環境變數，如果測試產生的指標與預期檔案中列出的不符，測試就會回報錯誤，並輸出差異。您可以視需要根據錯誤訊息中的差異手動更新預期檔案。

如何新增預期檔案

如果您要新增效能測試，可以按照下列步驟新增目標的預期檔案。

如為使用 fuchsia_component_perf_test GN 範本的測試，步驟包括手動建立預留位置預期檔案：

  1. 在 src/tests/end_to_end/perf/expected_metric_names/ 中建立空白的預期檔案預留位置版本。

  2. 在測試的 GN 宣告 (fuchsia_component_perf_test GN 範本叫用) 中新增 expected_metric_names_filepath 引數。

  3. 按照上述說明，使用 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR 組合在本機執行測試以產生檔案內容。

針對使用 python_perf_test GN 範本的測試，GN 和測試程式碼中都會指定預期檔案名稱。因此，您可以按照下列步驟操作，以免手動建立預留位置檔案：

  1. 將 expected_metric_names_filename 引數中的名稱傳遞至 Python 測試程式碼中的 publish_fuchsiaperf()。

  2. 在測試的 GN 宣告中設定 expected_metric_names_filepaths = [] (python_perf_test GN 範本叫用)。

  3. 按照上述方式設定 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR 後，在本機執行測試以產生檔案。

  4. 將 expected_metric_names_filepaths 設為測試 GN 宣告中預期檔案的實際清單。

  5. 使用 git add src/tests/end_to_end/perf/expected_metric_names/ 將預期檔案新增至 Git 結帳功能。

如果測試有多個預期檔案，這些步驟也適用於 python_perf_test。

您可以將檔案新增至 BUILD.gn 檔案，但如果檔案不存在，GN 建構作業就會失敗。

選用指標

預期檔案可能包含後置字串 [optional] 的項目。測試輸出內容中則不會顯示這些指標。這可讓指標是特定架構或機器專用的指標。也請加註說明這些指標的原因。(註解行以「#」開頭)。

如此一來，無論指標是否產生，都具備非確定性。不過，具有非確定性指標通常仍會視為應修正的錯誤。

略過指標摘要

使用 Python perf_publish 程式庫時，預設發布的 fuchsiaperf 檔案為摘要版本。

這項摘要有兩項值得注意的重點：

  • 我們會將每個頻道會員項目中的第一個值視為暖機執行並捨棄。
  • 同一個測試案例可能會有多個項目 (用於多個程序執行作業)，在這種情況下，我們會合併這些項目。

以此為後續處理步驟，有以下好處：

  • 如此一來，就不需要在上游 (在 C++ Perftest 程式庫或其他語言的類似程式庫中) 或下游消費者實作這項處理程序。
  • 因為摘要檔案比「原始資料」檔案小得多，因此更容易管理。
  • 如果使用者要分析原始資料，仍可使用「原始資料」附加資料檔案。

但在某些情況下，這並非理想：保留初始疊代時間而非捨棄它們，或允許向 Chromeperf 回報標準差並在圖表中顯示標準差。

因此，您可以在指標名稱預期檔案頂端加上 [no-summarize-metrics]，即可關閉摘要功能。