Подкоманда bencher run CLI

bencher run - самая популярная подкоманда CLI. Она используется для запуска тестов производительности и отчетов о результатах. Таким образом, она является одной из самых сложных подкоманд. На этой странице будет рассказано о параметрах, флагах и аргументах, которые можно передать bencher run.

bencher run [OPTIONS] [COMMAND] [ARGUMENTS...]

Команда бенчмарка

Первым аргументом для bencher run является необязательная команда бенчмарка. Это команда, которая будет выполнена и вызовет ваш harness для бенчмарков. Её также можно задать с помощью переменной окружения BENCHER_CMD. По умолчанию эта команда выполняется в shell, который можно настроить с помощью опций --shell и --flag. Её вывод парсится адаптером harness-а для бенчмарков — benchmark harness adapter, который можно задать с помощью опции --adapter. Однако, если harness для бенчмарков записывает результат в файл, то также должна быть использована опция --file для указания пути к файлу вывода. Альтернативно, чтобы отслеживать размер выходного файла (например, размер бинарника), а не его содержимое, используйте опцию --file-size для указания пути к файлу вывода.

Если вы не хотите, чтобы команда выполнялась в shell, вы можете использовать флаг --exec или просто передать дополнительные аргументы для вашей команды как дополнительные аргументы bencher run.

Shell Form:

bencher run "bencher mock"

Exec Form:

bencher run bencher mock

Команда бенчмарка может быть выполнена несколько раз с помощью опции --iter, а полученные результаты можно свернуть в единый результат с помощью опции --fold. Если какая-либо из итераций завершается неудачей, то вся команда считается провалившейся, если только не установлен флаг --allow-failure.

Если команда бенчмарка не указана, но указана опция --file, то bencher run просто прочитает данные из указанного файла. Аналогично, если команда бенчмарка не указана, но указана опция --file-size, то bencher run просто прочитает размер файла по указанному пути. Опции --file и --file-size можно указывать несколько раз, чтобы читать из нескольких файлов.

🐰 Советы по использованию опции -⁠-file

Опция -⁠-file может быть использована для чтения результатов бенчмарка из файла. Вы можете указывать опцию -⁠-file несколько раз, чтобы читать из нескольких файлов. Если вы укажете опцию -⁠-file несколько раз, то каждый файл будет рассматриваться как отдельная итерация команды бенчмарка. При отображении эти результаты будут показаны в отдельных таблицах.

Если вы хотите объединить эти результаты в одну итерацию, то вы можете установить опцию -⁠-iter в значение 1 и установить опцию -⁠-fold на одну из агрегирующих функций min, max или median. Это свернёт результаты в одну итерацию и отобразит их в одной таблице. Пожалуйста, не устанавливайте опцию -⁠-fold в значение mean.

Если не указаны ни команда бенчмарка, опция --file, ни опция --file-size, то bencher run будет читать из stdin. Это позволяет сохранить вывод другой команды в файл или перенаправить его в bencher run.

Options

--project <PROJECT>

Необязательно: либо опция --project, либо переменная окружения BENCHER_PROJECT может быть установлена в значение slug или UUID Проекта. Если указан slug и Проект ещё не существует, он будет создан автоматически. Если же указано UUID, Проект должен уже существовать. Если указаны оба варианта, опция --project имеет приоритет над переменной окружения BENCHER_PROJECT. Если ни один не указан, slug Проекта будет сгенерирован автоматически на основе:

1. имени родительской директории репозитория git, если он доступен.
2. 7-значного шестнадцатеричного короткого хеша начального коммита репозитория git, если он доступен.
3. 13-значного буквенно-цифрового отпечатка локальной машины для поддерживаемых операционных систем.

Например, сгенерированный slug Проекта может выглядеть так: project-abc4567-wxyz123456789

Когда для вас создаётся новый Проект, независимо от того, указан ли slug вручную или сгенерирован, Проект должен принадлежать Организации. Если пользователь аутентифицирован, Проект будет добавлен в личную Организацию этого пользователя. Если пользователь не аутентифицирован, Проект будет создан в новой Организации unclaimed. Эту Организацию затем можно claimed с публичной Perf Page проекта или, используя slug Проекта при аутентификации в последующем вызове bencher run.

🐰 ВАЖНО: Если переменная окружения CI установлена в true, то вам нужно либо указать проект, либо установить флаг --ci-on-the-fly.

--ci-on-the-fly

Опционально: разрешает создание динамических проектов в средах CI. Требуется, если переменная окружения CI установлена в true. Как GitHub Actions, так и GitLab CI/CD устанавливают эту переменную по умолчанию.

Конфликтует с опцией --project.

--token <TOKEN>

Необязательно: Либо опция --token, либо переменная окружения BENCHER_API_TOKEN может быть установлена в действительный API токен. Если оба заданы, опция --token имеет приоритет над переменной окружения BENCHER_API_TOKEN. Если ни один не задан, то проект должен быть незаявленным. То есть, если вы уже заявили проект, вы должны предоставить действительный API токен. Нажмите здесь, чтобы создать API токен.

--branch <BRANCH>

--hash <HASH>

--start-point <BRANCH>

--start-point-hash <HASH>

--start-point-max-versions <COUNT>

--start-point-clone-thresholds

--start-point-reset

См. Выбор ветки для полного обзора.

--testbed <TESTBED>

Необязательно: Либо опция --testbed, либо переменная окружения BENCHER_TESTBED могут быть установлены в имя, слаг или UUID для Тестового стенда. Если указанное значение — имя или слаг, и Тестовый стенд еще не существует, он будет создан для вас. Однако, если указанное значение — UUID, то Тестовый стенд должен уже существовать. Если указаны оба варианта, опция --testbed имеет приоритет над переменной окружения BENCHER_TESTBED. Если ни один из них не указан, то используются Linux, macOS или Windows, в зависимости от операционной системы хоста. Если bencher CLI был скомпилирован для другой операционной системы, тогда по умолчанию используется localhost в качестве Тестового стенда.

--threshold-measure <MEASURE>

--threshold-test <TEST>

--threshold-min-sample-size <SAMPLE_SIZE>

--threshold-max-sample-size <SAMPLE_SIZE>

--threshold-window <WINDOW>

--threshold-lower-boundary <BOUNDARY>

--threshold-upper-boundary <BOUNDARY>

--thresholds-reset

--err

Смотрите пороги и оповещения для полного обзора.

--adapter <ADAPTER>

--average <AVERAGE>

--file <FILE>

--build-time

--file-size <FILE>

Смотрите адаптеры оснастки для тестирования для полного обзора.

--iter <COUNT>

Опционально: Число повторений тестирования. По умолчанию 1.

--fold <AGGREGATE_FUNCTION>

Опционально: Возможность объединения нескольких результатов в один.
Требует: установки --iter.
Возможные значения:

• min: Минимальное значение
• max: Максимальное значение
• mean: Среднее значение
• median: Медианное значение

--backdate <SECONDS>

Опционально: Возможность отката даты отчета (секунды со времени эпохи). Внимание: Это не повлияет на порядок предыдущих отчетов! Это полезно при начальном занесении исторических данных в проект в хронологическом порядке.

--allow-failure

Опционально: Разрешить сбой теста производительности.

--format <FORMAT>

Необязательно: Формат итогового отчета. По умолчанию используется human.

Возможные значения:

• human: Человеко-читаемый формат
• json: Формат JSON
• html: Формат HTML

--quiet

Необязательно: Тихий режим, выводится только окончательный отчет. Используйте опцию --format, чтобы изменить формат вывода.

--github-actions <GITHUB_TOKEN>

Необязательно: Установите токен аутентификации API GitHub. Самый удобный способ сделать это - использовать переменную окружения GITHUB_TOKEN в GitHub Actions (например, --github-actions ${{ secrets.GITHUB_TOKEN }}). Когда эта опция установлена и bencher run используется в GitHub Actions как часть запроса на вытягивание, результаты будут добавлены в запрос как комментарий. Это требует, чтобы у токена были полномочия pull-requests с разрешениями на write. В противном случае результаты будут добавлены к коммиту как проверка GitHub. Это требует, чтобы у токена были полномочия checks с разрешениями на write. В любом случае, результаты также будут добавлены в сводку задания.

🐰 Если вы запускаете внутри контейнера Docker в GitHub Action, вам нужно будет передать следующие переменные окружения и смонтировать путь, указанный в GITHUB_EVENT_PATH:

• GITHUB_ACTIONS
• GITHUB_EVENT_NAME
• GITHUB_EVENT_PATH
• GITHUB_SHA
• GITHUB_API_URL (GitHub Enterprise Server только)

--ci-only-thresholds

Опционально: отправлять результаты в CI только если существует пороговое значение для ветки, тестовой среды и меры. Если пороговые значения отсутствуют, ничего отправляться не будет. Требуется: --github-actions

--ci-only-on-alert

Опционально: начинается публикация результатов в CI только если сгенерировано предупреждение. Если предупреждение сгенерировано, все последующие результаты также будут опубликованы, даже если они не содержат предупреждений. Требуется: --github-actions

--ci-id <ID>

Необязательно: Пользовательский идентификатор для отправки результатов в CI. По умолчанию Bencher автоматически сегментирует результаты по комбинации: Проект, Ветка, Тестовая среда и Адаптер. Установка пользовательского идентификатора полезна, когда Bencher запускается несколько раз в том же CI-потоке для той же комбинации Проекта, Ветки, Тестовой среды и Адаптера. Требуется: --github-actions

--ci-number <NUMBER>

Необязательно: номер задачи для отправки результатов на CI. Bencher постарается определить номер задачи CI, необходимый для отправки результатов. Однако это не всегда доступно в сложных настройках, таких как использование workflow_run в GitHub Actions. Требуется: --github-actions

--shell <SHELL>

Необязательный: Путь к командному интерпретатору. По умолчанию /bin/sh в UNIX-подобных средах и cmd в Windows.

--flag <FLAG>

Опционально: флаг команды оболочки. По умолчанию: -c в Unix-подобных средах и /C в Windows.

--exec

Необязательно: Запускать команду как исполняемый файл, а не как команду оболочки. По умолчанию, если количество аргументов для bencher run больше одного.

--host <URL>

Опционально: URL-адрес сервера бэкенда. По умолчанию используется Bench Cloud: https://api.bencher.dev

--insecure-host

Опционально: Разрешить небезопасное подключение к серверу Bencher API.

Этот флаг полезен, когда вы подключаетесь к локальной установке Bencher с самозаверяющим сертификатом или сертификатом, который не включен в хранилище сертификатов системы. Это применимо только к HTTPS-соединениям, так как HTTP-соединения изначально небезопасны.

ПРЕДУПРЕЖДЕНИЕ: Используйте --insecure-host только в безопасной сети с проверенными источниками, так как это обходит проверку SSL и может подвергнуть вас атакам типа “человек посередине”.

--native-tls

Необязательно: Загрузка TLS сертификатов из локального хранилища сертификатов платформы.

По умолчанию, bencher загружает сертификаты из встроенного webpki-roots крейта. webpki-roots представляют собой надежный набор доверенных корней от Mozilla, и их включение в bencher улучшает портативность и производительность. Это особенно актуально для macOS, где чтение системного хранилища доверия вызывает значительную задержку.

Однако в некоторых случаях, возможно, вы захотите использовать локальное хранилище сертификатов платформы, особенно если вы полагаетесь на корпоративный доверенный корень, включенный в системное хранилище сертификатов для обязательного прокси или самоподписанных Bencher Self-Hosted соединений.

--timeout <SECONDS>

Опционально: тайм-аут запроса в секундах. По умолчанию 15 секунд.

--attempts <COUNT>

Необязательно: Максимальное количество попыток повторного запроса. По умолчанию 10 попыток.

--retry-after <SECONDS>

Необязательно: начальное количество секунд ожидания между попытками (экспоненциальная задержка). По умолчанию 1 секунда.

--dry-run

Опционально: Выполнить пробный запуск. Это не сохранит никаких данных в бекенд. Ни Отчет, ни Ветвь (как описано в выбор ветви), ни Тестовая среда не будут созданы.

--help

Необязательно: Вывести справку.

🐰 Поздравляем! Вы изучили основы bencher run! 🎉

Продолжайте изучение: выбор ветки с bencher run ➡