Подкоманда 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:

Terminal window
bencher run "bencher mock"

Exec Form:

Terminal window
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 Проекта. Ключ API проекта нельзя использовать для создания нового Проекта или присвоения существующего Проекта, поэтому требуется, чтобы --project/BENCHER_PROJECT была установлена в существующий Проект. Если указан slug и Проект ещё не существует, он будет создан автоматически, когда используется ключ API пользователя (опция --key), устаревшая опция --token или учетные данные не предоставлены. Если же указано UUID, Проект должен уже существовать. Если указаны оба варианта, опция --project имеет приоритет над переменной окружения BENCHER_PROJECT. Если ни один не указан, slug Проекта будет сгенерирован автоматически на основе:

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

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

Когда для вас создаётся новый Проект, независимо от того, указан ли slug вручную или сгенерирован, Проект должен принадлежать Организации. Если пользователь аутентифицирован с помощью ключа API пользователя (опция --key) или устаревшей опции --token, Проект будет добавлен в личную Организацию этого пользователя. Если пользователь не аутентифицирован, Проект будет создан в новой Организации unclaimed. Эту Организацию затем можно claimed по ссылке Claim this project в выводе bencher run или, используя slug Проекта при аутентификации в последующем вызове bencher run.

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


--ci-on-the-fly


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

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


--key <KEY>


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

  • Ключ API пользователя (bencher_user_*) привязан к пользователю и выполняет аутентификацию от имени этого пользователя. Нажмите здесь, чтобы создать ключ API пользователя.
  • Ключ API проекта (bencher_run_*) ограничен одним проектом и может использоваться только для bencher run и других неразрушающих команд. Ключ API проекта нельзя использовать для создания нового Проекта или присвоения существующего Проекта, поэтому требуется, чтобы опция --project была установлена в существующий Проект.

Если не заданы ни опция --key, ни устаревшая опция --token, то Проект должен быть unclaimed. Конфликтует с устаревшей опцией --token.


--token <TOKEN>


🐰 УСТАРЕЛО: API токены устарели в пользу API ключей. Новые API токены больше нельзя создавать; существующие API токены продолжают работать. Используйте вместо этого опцию --key.

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


--image <IMAGE>

--entrypoint <ENTRYPOINT>

--env <KEY=VALUE>

--job-timeout <SECONDS>

--job-poll-interval <SECONDS>

--detach

--callback-url <URL>

--callback-header <NAME: VALUE>

--callback-body <JSON>

--job <UUID>


См. Образы для выделенного оборудования для полного обзора.


--branch <BRANCH>

--hash <HASH>

--start-point <BRANCH>

--start-point-hash <HASH>

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

--start-point-clone-thresholds

--start-point-reset

--start-point-idempotency-key <KEY>


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


--testbed <TESTBED>

--spec <SPEC>

--spec-reset


См. Испытательные платформы & Specs для полного обзора.


--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

--error-on-alert


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


--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 }}).

Результаты будут добавлены к head-коммиту как проверка GitHub с именем:

  1. Bencher Report (<ID>), если задана опция --ci-id
  2. Bencher Report (<ИМЯ ПРОЕКТА>) для существующих проектов
  3. Bencher Report для динамических проектов --ci-on-the-fly (пока проверка выполняется)

Это требует, чтобы у токена были полномочия checks с разрешениями на write. Если проверку GitHub не удается создать, bencher run запишет предупреждение в журнал и продолжит работу.

Когда bencher run используется как часть запроса на вытягивание, результаты также будут добавлены в запрос как комментарий. Все задания Проекта в запросе на вытягивание используют этот один общий комментарий, с одной строкой Отчета для каждого задания. Это требует, чтобы у токена были полномочия pull-requests с разрешениями на write. Результаты также всегда будут добавлены в сводку задания. С флагом --detach отсоединенный запуск не публикует комментарий и не пишет сводку задания, а подключение с помощью --job завершает проверку GitHub, которую он запустил (см. опцию --ci-callback-token).

Если строк две или больше, комментарий показывает таблицу сводки каждого Отчета с каждой из его Ветки, Тестовой среды и Адаптера, которые различаются между Отчетами, и со статусом (Pending, число предупреждений, No Alerts или Failed). Строки идут в порядке запуска Отчетов и пронумерованы с 1, так же как Console перечисляет Отчеты одного запуска. Подпись каждой строки состоит из ее номера, за которым в скобках следует значение опции --ci-id, если она задана (пример: 2 (microbench)). Подпись ведет на Отчет, ячейка Тестовой среды на ее страницу в Console, а ячейка Адаптера на его часть документации по Адаптерам. Ветка, Тестовая среда или Адаптер, которые одинаковы во всех Отчетах, переходят из таблицы сводки в таблицу в начале комментария, которая ссылается на них так же. Далее одна таблица содержит предупреждения всех Отчетов, со столбцом для Отчета. Затем результаты каждого Отчета следуют в сворачиваемом блоке (пример: Report 2 (microbench): 14 benchmarks, 2 alerts), который открыт, если в Отчете есть предупреждения. Каждое задание сохраняет свою проверку GitHub и свою сводку задания, поэтому имена проверок GitHub и обязательные проверки статуса не меняются. Задание, чей коммит больше не является head-коммитом запроса на вытягивание, оставляет комментарий без изменений. Если токен не может прочитать запрос на вытягивание, то задание запишет предупреждение в журнал и напишет комментарий без проверки head-коммита.

У комментария GitHub есть ограничение размера, поэтому комментарий использует первую из этих форм, которая помещается:

  1. Все части выше
  2. Без сворачиваемых блоков, с пометкой, что комментарий сокращен
  3. Каждая строка сводки и общее число предупреждений, без строк предупреждений
  4. В крайнем случае первые строки сводки, а затем and N more reports для остальных

С одной строкой комментарий такой же, как раньше, а если он слишком большой, он ведет на полный Отчет.

Чтобы найти другие задания, bencher run получает список проверок GitHub для head-коммита, что уже разрешают указанные выше полномочия checks с разрешениями на write. Если задание не может создать или завершить свою проверку GitHub, не может определить, какому GitHub App она принадлежит, или не может получить список проверок GitHub, то оно опубликует комментарий только со своими результатами. Комментарии Проекта от более ранней версии bencher run заменяются: первое задание, которое пишет общий комментарий, обновляет самый старый из них и удаляет остальные. При записи общего комментария задание обновляет или удаляет только комментарии, опубликованные GitHub App, которому принадлежит его проверка GitHub, то есть ботом github-actions при использовании GITHUB_TOKEN.

🐰 Если вы запускаете внутри контейнера 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 создается всегда. Требуется: --github-actions


--ci-only-on-alert


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


--ci-id <ID>


Необязательно: Пользовательский идентификатор для отправки результатов в CI. Все задания Проекта в запросе на вытягивание используют один общий комментарий, с одной строкой Отчета для каждого задания. С идентификатором подписью строки служат ее номер и идентификатор (пример: 2 (microbench)). Пока Отчет задания не существует, его строка показывает только идентификатор без номера (пример: (microbench)), со статусом Pending, пока задание выполняется, и идет после пронумерованных строк. Без идентификатора подписью служит только номер, а строка появляется, как только Отчет задания существует. По умолчанию задания используют одну строку, если у них одинаковая комбинация: Ветка, Тестовая среда и Адаптер, а также --build-time и --file-size, если они заданы. Установка пользовательского идентификатора полезна, когда Bencher запускается несколько раз на одном и том же коммите для той же комбинации Проекта, Ветки, Тестовой среды и Адаптера, чтобы у каждого запуска была своя строка. Например, запуск по push и запуск по pull_request в одной ветке используют один и тот же head-коммит, поэтому задайте каждому запуску свой идентификатор или не используйте --github-actions для запуска по push. Иначе запуски используют одну строку, которая показывает только один из них, а более старый запуск ничего не пишет, как только строку занимает более новый запуск. Идентификатор также используется вместо имени Проекта в имени проверки GitHub (например, Bencher Report (<ID>)), поэтому каждый запуск получает стабильное имя, которое можно использовать как отдельную обязательную проверку статуса. Требуется: --github-actions


--ci-number <NUMBER>


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



Необязательно: все ссылки должны вести на публичные URL-адреса, не требующие входа в систему. Требуется: --github-actions


--ci-callback-token <TOKEN>


Необязательно: Задает токен аутентификации, который использует callback отсоединенного Job на выделенном оборудовании.

При использовании флага --detach и опции --github-actions API-сервер Bencher запускает workflow repository_dispatch, когда Job завершается. Для Проекта со связанным репозиторием Bencher создает токен сам, поэтому эта опция не нужна. Чтобы вместо этого использовать собственный токен, укажите в этой опции детализированный персональный токен доступа для репозитория как минимум с разрешением contents: write. Тогда Bencher отправляет событие repository_dispatch с этим токеном, есть ли у Проекта связанный репозиторий или нет. CLI требует эту опцию на GitHub Enterprise Server и с API-сервером Bencher версии ниже v0.6.16. Без нее отсоединенный запуск claimed Проекта отклоняется, если у сервера нет приложения GitHub, у Проекта нет связанного репозитория или его связанный репозиторий отключен. См. Pull Requests на выделенном оборудовании в GitHub Actions для полного обзора.

🐰 Здесь нельзя просто использовать GITHUB_TOKEN, так как срок его действия истекает сразу после завершения текущего workflow!


--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>


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


--retry-after <SECONDS>


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


--max-retry-after <SECONDS>


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


--dry-run


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


--help


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



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


Продолжайте изучение: Образы для выделенного оборудования ➡

🤖 Этот документ был автоматически переведён с помощью ИИ. Он может быть неточным и содержать ошибки. Если вы обнаружите какие-либо ошибки, откройте проблему на GitHub.


Published: Fri, October 27, 2023 at 8:40:00 AM UTC | Last Updated: Thu, October 29, 2026 at 4:53:42 AM UTC