指標名稱預期檔案

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 宣告 (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 宣告 (python_perf_test GN 範本叫用) 中設定 expected_metric_names_filepaths = []。

  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] 的項目。這些指標可以在測試輸出中缺席。這可讓指標依架構或機器而異。這些指標應附註說明為何為選用指標。(註解行開頭為「#」)。

這也讓指標在產生與否方面不具決定性。不過，如果指標不具決定性，通常會視為需要修正的錯誤。

停用指標

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

略過指標摘要

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

這項摘要功能有兩個值得一提的優點：

  • 我們會將每個 fuchsiaperf 項目中的首個值視為預熱執行作業，並將其捨棄。
  • 同一個測試案例可能會有多個項目 (針對多個程序執行作業)，在這種情況下，我們會合併這些項目。

將此做為後置處理步驟的好處如下：

  • 這樣一來，您就不必在上游 (C++ 效能測試程式庫或其他語言的類似程式庫) 或下游使用者端實作這項處理作業。
  • 摘要 fuchsiaperf 檔案比「原始資料」fuchsiaperf 檔案小得多，因此更容易管理。
  • 任何想分析原始資料的使用者，仍可使用「原始資料」fuchsiaperf 檔案。

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

因此，只要在指標名稱預期值檔案頂端新增 [no-summarize-metrics]，即可關閉摘要功能。