Mach Try Perf

为了方便开发人员找到他们需要运行的测试，我们构建了一个特定于性能的 try 选择器，称为 ./mach try perf。使用此工具，您不再需要记住需要针对测试的目标的模糊平台和测试名称。相反，新界面显示了测试类别以及它们将在其上运行的平台的简化名称。

当您从性能选择器触发 try 运行时，将创建两个 try 运行。一个包含您的更改，另一个不包含。不包含您的更改的推送将在您的补丁所基于的修订版上执行（我们将其称为基准修订版）。在您的控制台中，在您触发 try 运行后，您会找到一个 PerfCompare 链接，该链接将在它们完成后直接带您到这两个推送的比较。

该工具在要运行的测试数量方面非常保守，因此，如果您正在寻找未列出的内容，它可能隐藏在 --help 中找到的标志后面。以下是您将在那里找到的内容列表

$ ./mach try perf --help

optional arguments:
  -h, --help            show this help message and exit
perf arguments:
  --show-all            Show all available tasks.
  --android             Show android test categories (disabled by default).
  --chrome              Show tests available for Chrome-based browsers (disabled by
                        default).
  --custom-car          Show tests available for Custom Chromium-as-Release (disabled by
                        default). Use with --android flag to select Custom CaR android
                        tests (cstm-car-m)
  --safari              Show tests available for Safari (disabled by default).
  --safari-tp           Show tests available for Safari Technology Preview(disabled by
                        default).
  --live-sites          Run tasks with live sites (if possible). You can also use the
                        `live-sites` variant.
  --profile             Run tasks with profiling (if possible). You can also use the
                        `profiling` variant.
  --single-run          Run tasks without a comparison
  -q QUERY, --query QUERY
                        Query to run in either the perf-category selector, or the fuzzy
                        selector if --show-all is provided.
  --browsertime-upload-apk BROWSERTIME_UPLOAD_APK
                        Path to an APK to upload. Note that this will replace the APK
                        installed in all Android Performance tests. If the Activity,
                        Binary Path, or Intents required change at all relative to the
                        existing GeckoView, and Fenix tasks, then you will need to make
                        fixes in the associated taskcluster files (e.g.
                        taskcluster/kinds/test/browsertime-mobile.yml). Alternatively, set
                        MOZ_FIREFOX_ANDROID_APK_OUTPUT to a path to an APK, and then run
                        the command with --browsertime-upload-apk firefox-android. This
                        option will only copy the APK for browsertime, see --mozperftest-
                        upload-apk to upload APKs for startup tests.
  --mozperftest-upload-apk MOZPERFTEST_UPLOAD_APK
                        See --browsertime-upload-apk. This option does the same thing
                        except it's for mozperftest tests such as the startup ones. Note
                        that those tests only exist through --show-all as they aren't
                        contained in any existing categories.
  --detect-changes      Adds a task that detects performance changes using MWU.
  --comparator COMPARATOR
                        Either a path to a file to setup a custom comparison, or a builtin
                        name. See the Firefox source docs for mach try perf for examples
                        of how to build your own, along with the interface.
  --comparator-args [ARG=VALUE [ARG=VALUE ...]]
                        Arguments provided to the base, and new revision setup stages of
                        the comparator.
  --variants [ [ ...]]  Select variants to display in the selector from: fission,
                        bytecode-cached, live-sites, profiling, swr
  --platforms [ [ ...]]
                        Select specific platforms to target. Android only available with
                        --android. Available platforms: android-a51, android, windows,
                        linux, macosx, desktop
  --apps [ [ ...]]      Select specific applications to target from: firefox, chrome,
                        geckoview, fenix, chrome-m, safari, safari-tp, custom-car, cstm-
                        car-m
  --clear-cache         Deletes the try_perf_revision_cache file
  --alert ALERT         Run all tests that produced this alert summary ID based on the
                        alert summary table in either the alerts view or the regression
                        bug. The comparison that is produced will be based on the base
                        revision in your local repository (i.e. the base revision your
                        patches, if any, are based on). If only specific tests need to
                        run, use --tests to specify them (e.g. --tests webaudio).
  --extra-args [ [ ...]]
                        Set the extra args (e.x, --extra-args verbose post-startup-
                        delay=1)
  --non-pgo             Use opt/non-pgo builds instead of shippable/pgo builds. Setting
                        this flag will result in faster try runs.
  --tests [TESTS [TESTS ...]], -t [TESTS [TESTS ...]]
                        Select from all tasks that run these specific tests (e.g. amazon, or
                        speedometer3).

task configuration arguments:
  --artifact            Force artifact builds where possible.
  --no-artifact         Disable artifact builds even if being used locally.
  --browsertime         Use browsertime during Raptor tasks.
  --disable-pgo         Don't run PGO builds
  --env ENV             Set an environment variable, of the form FOO=BAR. Can
                        be passed in multiple times.
  --gecko-profile       Create and upload a gecko profile during talos/raptor
                        tasks.
  --gecko-profile-interval GECKO_PROFILE_INTERVAL
                        How frequently to take samples (ms)
  --gecko-profile-entries GECKO_PROFILE_ENTRIES
                        How many samples to take with the profiler
  --gecko-profile-features GECKO_PROFILE_FEATURES
                        Set the features enabled for the profiler.
  --gecko-profile-threads GECKO_PROFILE_THREADS
                        Comma-separated list of threads to sample.
  paths                 Run tasks containing tests under the specified
                        path(s).
  --rebuild [2-20]      Rebuild all selected tasks the specified number of
                        times.

工作流程

下面，您将找到 ./mach try perf 中可用功能的概述。如果您想详细了解如何使用此工具来增强您的开发流程，请参阅 使用 Mach Try Perf 的标准工作流程 页面。

标准用法

要使用 mach try perf，只需调用 ./mach try perf。这将打开一个用于测试选择的界面，如下所示

选择您要运行的类别，按 Enter 键，然后等待工具完成推送。**请注意，执行这两个推送可能需要一些时间，并且您可能在一段时间内看不到日志。**

重新触发

推送完成后，您将收到一个 Treeherder 链接，您可以打开它来查看您的推送。访问 Treeherder 链接以查看所有测试。

要启动重新触发，首先选择要重新触发的任务

然后，单击任务操作栏中的旋转箭头图标，或按键盘上的“r”

此外，您可以将标志 --rebuild=2-20 添加到 try perf 命令中以指定要运行测试的次数。如果您想详细了解重新触发，请 访问此页面。

添加新任务（批量重新触发）

添加新任务功能可用于多次重新触发许多任务。要添加新任务，请按照以下步骤操作

• 导航到您要在 Treeherder 上添加任务的推送。

• 单击推送右上角的箭头下拉菜单。

• 从菜单中选择 自定义推送操作。

您可以从 Decision 任务的 target-tasks.json 文件中复制值并将其粘贴到 task 选项中。如果需要，此方法可用于批量重新触发。粘贴 json 值后，按下 触发 按钮。

理想情况下，您应该能够使用比较视图更具体地指定要对显示差异的任务/测试进行的重新触发，以便他们想要仔细检查。

向 try 运行添加额外参数/选项

要向 try 运行添加其他参数，您可以考虑几种方法

使用 Treeherder

此方法假设您已经拥有已运行的任务，并且您想再次运行它，但这次还要添加其他选项。首先选择要添加其他选项的任务

然后，单击任务操作栏中的三个点图标，然后选择 自定义操作

将打开一个窗口，您需要在其中选择 raptor-extra-options。您可以在那里添加所有需要的选项（例如 extra_options: ‘verbose browser-cycles=3’）。完成后，按下 触发 按钮。

修改 yml 文件

此方法涉及识别包含您感兴趣的测试的 YML 文件，并修改或添加 extra-options 键。在此键下，您可以添加所有所需的参数。

使用 extra-args 选项

另一种方法是利用 --extra-args 参数到 try perf 命令（例如 –extra-args verbose post-startup-delay=1）。

运行警报测试

要运行触发给定警报的所有测试，请使用 ./mach try perf --alert <ALERT-NUMBER>。使用此命令将运行在回归错误中提供的警报摘要 ID 生成器产生的所有测试。**建议在处理性能警报时使用此方法。**警报编号可以在任何警报错误的注释 0 中找到 例如这个。如下图所示，警报编号可以在摘要表上方找到。生成的比较将基于您本地存储库中的基准修订版（即您的补丁（如果有）所基于的基准修订版）。

运行特定测试的任务

使用 --tests 选项，您可以运行运行特定测试的所有任务。这基于在任务中运行的命令中使用的测试名称。对于 raptor，这是由 --test 指定的测试。对于 talos，它可以是套件中的特定测试，例如 tp5n 来自 xperf，或者可以指定套件 xperf。但是，对于 AWSY，没有可以选择的特定测试，因此选择 awsy 测试的唯一选项是将 awsy 指定为测试。

如果它与 --alert <NUM> 一起使用，则只有运行特定测试的任务将在 try 上运行。如果它与 --show-all 一起使用，则您只会看到在模糊界面中运行特定测试的任务。最后，如果它不与其中任何一个一起使用，则将在模糊界面中显示指定测试的类别。例如，如果使用 --tests amazon，则将显示 amazon linux firefox 或 amazon desktop 等类别。

Chrome 和 Android

Android 和 chrome 测试默认情况下是禁用的，因为它们通常不需要并且会浪费我们有限的资源。如果您需要其中任何一个，您可以添加 --chrome 和/或 --android 到命令中，如下所示 ./mach try perf --android --chrome

变体

如果您正在寻找任何变体（例如 no-fission、bytecode-cached、live-sites），请使用 --variants 选项，如下所示 ./mach try perf --variants live-sites。这将选择所有可能包含 live-sites 测试的类别。

请注意，提供的类别预计会有额外的变体（例如 bytecode-cached），因为我们显示了所有可能包含 live-sites 的组合。

平台

要定位特定平台，您可以使用 --platforms 仅显示具有给定平台的类别。

类别

将来，本节将动态填充。如果您想知道您选择的类别将运行什么，您可以使用 --no-push 打印出将运行的任务列表，如下所示

$ ./mach try perf --no-push

Artifact builds enabled, pass --no-artifact to disable
Gathering tasks for Benchmarks desktop category
Executing queries: 'browsertime 'benchmark, !android 'shippable !-32 !clang, !live, !profil, !chrom
estimates: Runs 66 tasks (54 selected, 12 dependencies)
estimates: Total task duration 8:45:58
estimates: In the shortest 38% of durations (thanks!)
estimates: Should take about 1:04:58 (Finished around 2022-11-22 15:08)
Commit message:
Perf selections=Benchmarks desktop (queries='browsertime 'benchmark&!android 'shippable !-32 !clang&!live&!profil&!chrom)
Pushed via `mach try perf`
Calculated try_task_config.json:
{
    "env": {
        "TRY_SELECTOR": "fuzzy"
    },
    "tasks": [
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-ares6",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-assorted-dom",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-jetstream2",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-matrix-react-bench",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-motionmark-animometer",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-motionmark-htmlsuite",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-speedometer",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-stylebench",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-sunspider",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-twitch-animation",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-unity-webgl",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-firefox-webaudio",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot-baseline",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot-optimizing",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc-baseline",
        "test-linux1804-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc-optimizing",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-ares6",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-assorted-dom",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-jetstream2",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-matrix-react-bench",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-motionmark-animometer",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-motionmark-htmlsuite",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-speedometer",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-stylebench",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-sunspider",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-twitch-animation",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-unity-webgl",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-firefox-webaudio",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot-baseline",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot-optimizing",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc-baseline",
        "test-macosx1015-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc-optimizing",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-ares6",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-assorted-dom",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-jetstream2",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-matrix-react-bench",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-motionmark-animometer",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-motionmark-htmlsuite",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-speedometer",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-stylebench",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-sunspider",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-twitch-animation",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-unity-webgl",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-firefox-webaudio",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot-baseline",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-godot-optimizing",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc-baseline",
        "test-windows10-64-shippable-qr/opt-browsertime-benchmark-wasm-firefox-wasm-misc-optimizing"
    ],
    "use-artifact-builds": true,
    "version": 1
}

添加新类别

如果需要，添加新类别非常容易，您可以通过修改 此处的 PerfParser 类别属性 来实现。以下是一个复杂类别的示例，它很好地说明了您可用的内容

"Resource Usage": {
    "query": {
        "talos": ["'talos 'xperf | 'tp5"],
        "raptor": ["'power 'osx"],
        "awsy": ["'awsy"],
    },
    "suites": ["talos", "raptor", "awsy"],
    "platform-restrictions": ["desktop"],
    "variant-restrictions": {
        "raptor": [],
        "talos": [],
    },
    "app-restrictions": {
        "raptor": ["firefox"],
        "talos": ["firefox"],
    },
    "tasks": [],
},

以下字段可用

• **query**：设置每个所需的套件要使用的查询。

• **suites**：此类别所需的套件。

• **tasks**：要选择的硬编码任务列表。

• **platform-restrictions**：它可以在其上运行的平台。

• **app-restrictions**：类别可以运行的应用列表。

• **variant-restrictions**：每个套件可用的变体列表。

请注意，设置 App/Variant-Restriction 字段应该用于限制可用的应用程序和变体，而不是扩展它们，因为套件、应用程序和平台的组合已经提供了最大的覆盖范围。当您知道某些特定内容肯定无法工作，或者永远不会为此类测试实现时，才应使用这些限制。例如，我们的 Resource Usage 测试仅适用于 Firefox，即使它们可能存在于 Raptor 中，而 Raptor 可以运行 Chrome 测试。

比较器

如果标准/默认的推送到尝试比较不够，您可以构建自己的“比较器”，它可以设置基线和新版本。默认比较器 BasePerfComparator 运行标准的 mach-try-perf 比较，并且还存在一个名为 BenchmarkComparator 的自定义比较器，用于在尝试时运行自定义基准测试比较（使用 Github PR 链接）。

如果您想添加自定义比较器，您可以将其创建在单独的文件中并将其传递给 --comparator，或者将其添加到 tools/tryselect/selectors/perfselector/perfcomparators.py 中，并将类的名称用作 --comparator 参数（例如 --comparator BenchmarkComparator）。您可以使用接受格式为 NAME=VALUE 的参数的 --comparator-args 选项向其传递其他参数。

自定义比较器需要是 BasePerfComparator 的子类，并可以选择覆盖其方法。有关可用接口的更多信息，请参阅比较器文件。以下是其通用接口（可能会有所更改），请注意，在创建内置比较器时需要 @comparator 装饰器

@comparator
class BasePerfComparator:
    def __init__(self, vcs, compare_commit, current_revision_ref, comparator_args):
        """Initialize the standard/default settings for Comparators.

        :param vcs object: Used for updating the local repo.
        :param compare_commit str: The base revision found for the local repo.
        :param current_revision_ref str: The current revision of the local repo.
        :param comparator_args list: List of comparator args in the format NAME=VALUE.
        """

    def setup_base_revision(self, extra_args):
        """Setup the base try run/revision.

        The extra_args can be used to set additional
        arguments for Raptor (not available for other harnesses).

        :param extra_args list: A list of extra arguments to pass to the try tasks.
        """

    def teardown_base_revision(self):
        """Teardown the setup for the base revision."""

    def setup_new_revision(self, extra_args):
        """Setup the new try run/revision.

        Note that the extra_args are reset between the base, and new revision runs.

        :param extra_args list: A list of extra arguments to pass to the try tasks.
        """

    def teardown_new_revision(self):
        """Teardown the new run/revision setup."""

    def teardown(self):
        """Teardown for failures.

        This method can be used for ensuring that the repo is cleaned up
        when a failure is hit at any point in the process of doing the
        new/base revision setups, or the pushes to try.
        """

常见问题解答 (FAQ)

如果您有任何以下未解答的问题，请通过 perftest 矩阵频道 联系我们。

• 如何确定类别或一组选择将运行什么内容？

  目前，您需要使用其他选项运行命令才能查看将要运行的内容：./mach try perf --no-push。有关此内容的更多信息，请参阅 类别 部分。将来，我们计划在本文档的 类别 部分中提供任务的动态更新列表。

• ``Pageload desktop`` 和 ``Pageload desktop firefox`` 之间有什么区别？

  如果您只是运行 ./mach try perf 且没有其他选项，则两者之间没有区别。如果您开始使用诸如 ./mach try perf --chrome 之类的命令向尝试运行中添加其他浏览器，则 Pageload desktop 将选择所有可用于所有可用浏览器的测试，而 Pageload desktop firefox 将仅选择 Firefox 测试。提供 --chrome 时，您还会看到 Pageload desktop chrome 选项。

• 帮助！我在任何类别中都找不到测试。我该怎么办？

  使用选项 --show-all。这将允许您直接从 ./mach try fuzzy --full 接口而不是类别中选择测试。您始终可以通过这种方式找到您的测试。但是请谨慎选择任务，因为通过这种方式很容易运行过多的测试！

未来工作

此工具的未来工作可以在 此错误 中找到。请随时提交改进和错误。