指標名稱預期檔案

Fuchsia 的成效測試結果回報基礎架構，有一組已簽入的預期指標名稱，各項成效測試可能會產生這些指標。這也稱為指標名稱許可清單。這項功能已在 https://fxbug.dev/42056406 中新增。

如果效能測試產生的一組指標與測試期望檔案中列出的指標不符，測試執行時就會失敗。也就是說，如果測試有所變更，導致產生的指標組合也隨之變更，則必須更新測試的期望值檔案，以符合變更內容。

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

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

預期福利

  • 期望檔案的用途是協助維持指標命名一致性。這些工具應可簡化指標命名審查作業，並透過 OWNERS 檢查強制執行審查。

  • 測試作者應能透過期望檔案，更輕鬆地查看其他使用的指標名稱，以便進行比較，因為清單會簽入程式碼集。

  • 您應該可以透過期望檔案，更輕鬆地查看特定 CL 的產生指標清單有何變更。開發人員可藉此確保 CL 未意外移除或重新命名指標。

  • 期望檔案會檢查新增的指標數量。因為加入大量指標會產生費用，所以這項功能十分實用。

  • 期望值檔案應能確保測試產生的指標集具有確定性。指標可能會動態產生，且產生方式有很多種。也就是說，如果沒有預期檢查，測試的一組指標可能會是不確定的。這會導致 CI 建構產生的資料出現隨機間隙，因此不建議使用。

如何更新期望檔案

如要更新測試的期望結果檔案，其中一種方法是在本機執行測試，並設定 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR 環境變數，例如使用下列叫用方式：

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

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

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

如何新增期望檔案

如要新增效能測試，請按照下列步驟新增預期結果檔案。

如果是使用 fuchsia_component_perf_test GN 範本進行測試，請手動建立預期結果的預留位置檔案，步驟如下：

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

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

  3. 如上所述，使用 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR 設定在本機執行測試，產生檔案內容。

如要使用 python_perf_test GN 範本進行測試，GN 和測試程式碼都會指定預期檔案名稱，因此只要按照下列步驟操作，即可避免手動建立預留位置檔案的不便：

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

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

  3. 如上所述，使用 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR set 在本機執行測試，產生檔案。

  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] 的項目。測試輸出內容中可以沒有這些指標。因此指標可以是架構專屬或機器專屬。這些指標應加上註解，說明為何為選用項目。(註解行開頭為「#」)。

這也表示指標是否產生是不確定的。不過，如果指標不具確定性，通常會視為應修正的錯誤。

停用指標

如果指標已停用，且目前狀態的程式碼永遠不會產生該指標，最好從清單中移除指標或註解掉，而不是將其標示為選用。否則，當指標重新啟用時，我們可能會忘記移除 [optional] 標記，這表示如果指標稍後遺失，我們不會注意到。

略過指標摘要

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

這項摘要功能有兩項值得注意的優點：

  • 我們會將每個 fuchsiaperf 項目中的第一個值視為暖身執行，並捨棄該值。
  • 同一個測試案例可能會有多個項目 (適用於多個程序執行)，這時我們會合併這些項目。

以後續處理步驟執行這項操作有以下優點：

  • 這樣一來，您就不必在上游 (在 C++ perftest 程式庫中，或在其他語言的類似程式庫中) 或下游消費者中實作這項處理程序。
  • 摘要 fuchsiaperf 檔案比「原始資料」fuchsiaperf 檔案小得多，因此更容易管理。
  • 如果有人想分析原始資料，我們仍可提供「原始資料」fuchsiaperf 檔案。

不過，在某些情況下，這可能並非理想做法：為了保留初始疊代的時間，而不是捨棄這些時間，或是為了允許將標準差回報給 Chromeperf，並顯示在圖表中。

因此，只要在指標名稱期望檔案頂端加入 [no-summarize-metrics]，即可為整個檔案關閉摘要功能；如要為個別指標關閉摘要功能，則只要在期望檔案中指標項目的結尾加入 [no-summarize] 即可。