bencher run CLI 하위 명령어
bencher run은 가장 인기 있는 CLI 하위 명령어입니다.
이는 벤치마크를 실행하고 결과를 보고하는 데 사용됩니다.
따라서 가장 복잡한 하위 명령어 중 하나입니다.
이 페이지에서는 bencher run에 전달할 수 있는 옵션, 플래그, 인수에 대해 설명합니다.
bencher run [OPTIONS] [COMMAND] [ARGUMENTS...]벤치마크 명령
bencher run의 첫 번째 인수는 선택적 벤치마크 명령입니다.
이 명령은 벤치마크 하니스(benchmark harness)를 호출하는 데 사용됩니다.
또한 BENCHER_CMD 환경 변수로 설정할 수 있습니다.
기본적으로 이 명령은 셸에서 실행되며,
이는 --shell 및 --flag 옵션으로 구성할 수 있습니다.
명령의 출력은 benchmark harness adapter로 파싱되며,
이는 --adapter 옵션으로 설정할 수 있습니다.
그러나 벤치마크 하니스가 파일로 출력을 내보내는 경우에는 출력 파일 경로를 지정하기 위해 --file 옵션도 사용해야 합니다.
또는 출력 내용 대신 출력 파일의 크기(예: 바이너리 크기)를 추적하려면 출력 파일 경로를 지정하기 위해 --file-size 옵션을 사용하세요.
명령을 셸에서 실행하지 않으려면 --exec 플래그를 사용하거나 명령에 대한 추가 인수를 bencher run에 추가 인수로 제공하면 됩니다.
셸 형식:
bencher run "bencher mock"Exec 형식:
bencher run bencher mock벤치마크 명령은 --iter 옵션을 사용하여 여러 번 실행할 수 있으며,
그 결과는 --fold 옵션을 사용해 단일 결과로 합칠 수 있습니다.
만약 반복(iteration) 중 하나라도 실패하면,
--allow-failure 플래그가 설정되어 있지 않는 한 전체 명령이 실패한 것으로 간주됩니다.
벤치마크 명령이 지정되지 않았지만 --file 옵션이 지정되어 있으면,
bencher run은 대신 출력 파일 경로에서 읽기만 합니다.
마찬가지로 벤치마크 명령이 지정되지 않았지만 --file-size 옵션이 지정되어 있으면,
bencher run은 지정된 파일 경로의 파일 크기만 읽습니다.
--file 및 --file-size 옵션은 여러 번 지정하여 여러 파일에서 읽을 수 있습니다.
🐰
--file옵션 사용 팁--file옵션은 파일에서 벤치마크 결과를 읽을 때 사용할 수 있습니다. 여러 파일에서 읽으려면--file옵션을 여러 번 지정할 수 있습니다. 옵션을 여러 번 지정하면 각 파일이 벤치마크 명령의 별도iteration으로 간주됩니다. 표시될 때 이 결과들은 각각 별도의 표로 출력됩니다.결과들을 하나의
iteration으로 합치려면--iter옵션을1로 설정하고--fold옵션을 집계 함수 중min,max또는median으로 설정하면 됩니다. 그러면 결과들이 하나의iteration으로 합쳐져 하나의 표로 표시됩니다. 절대--fold옵션을mean으로 설정하지 마세요.
벤치마크 명령도, --file 옵션도, --file-size 옵션도 지정되지 않은 경우,
bencher run은 대신 stdin에서 읽습니다.
이를 통해 다른 명령의 출력을 파일로 저장하거나 파이프를 통해 bencher run으로 전달할 수 있습니다.
Options
--project <PROJECT>
선택 사항: --project 옵션이나 BENCHER_PROJECT 환경 변수를 프로젝트의 슬러그 또는 UUID로 설정할 수 있습니다.
프로젝트 API 키는 새 프로젝트를 생성하거나 기존 프로젝트를 청구하는 데 사용할 수 없으므로, --project/BENCHER_PROJECT가 기존 프로젝트로 설정되어 있어야 합니다.
지정된 값이 슬러그이고 해당 프로젝트가 존재하지 않으면, 사용자 API 키(--key 옵션), 사용 중단된 --token 옵션이 사용되거나 자격 증명이 전혀 제공되지 않은 경우에 프로젝트가 자동으로 생성됩니다.
반면에 값이 UUID인 경우 해당 프로젝트는 이미 존재해야 합니다.
둘 다 지정된 경우 --project 옵션이 BENCHER_PROJECT 환경 변수보다 우선합니다.
둘 다 지정되지 않으면 다음을 기반으로 프로젝트 슬러그가 생성됩니다:
- 가능한 경우
git저장소의 상위 디렉터리 이름. - 가능한 경우
git저장소 초기 커밋의 7자리 16진수 단축 해시. - 지원되는 운영체제에서 로컬 머신의 13자리 영숫자 지문.
예: 생성된 프로젝트 슬러그는 다음과 같을 수 있습니다: project-abc4567-wxyz123456789
새 프로젝트가 생성될 때(슬러그가 지정되었든 생성되었든), 프로젝트는 반드시 조직에 속해야 합니다.
사용자가 사용자 API 키(--key 옵션) 또는 사용 중단된 --token 옵션으로 인증된 경우, 프로젝트는 해당 사용자의 개인 조직 아래에 추가됩니다.
사용자가 인증되지 않은 경우 프로젝트는 새 unclaimed 조직 아래에 생성됩니다.
이 조직은 이후 프로젝트의 공개 Perf 페이지에서 claimed 하거나, 이후 인증된 상태로 bencher run을 실행할 때 프로젝트 슬러그를 사용하여 claimed할 수 있습니다.
🐰 중요: 만약
CI환경 변수가true로 설정되어 있으면, 프로젝트를 지정하거나--ci-on-the-flyflag를 설정해야 합니다.
--ci-on-the-fly
옵션: CI 환경에서 즉석 프로젝트 생성을 허용합니다.
CI 환경 변수가 true로 설정된 경우 필요합니다.
GitHub Actions과 GitLab CI/CD 모두 이 변수를 기본적으로 설정합니다.
--project option과 충돌합니다.
--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
자세한 내용은 베어 메탈 이미지를 참조하세요.
--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>
--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>
전체 개요는 benchmark harness adapter를 참조하세요.
--iter <COUNT>
선택사항: 실행 반복 횟수입니다. 기본값은 1입니다.
--fold <AGGREGATE_FUNCTION>
선택사항: 여러 결과들을 하나의 결과로 병합합니다.
필요사항: --iter가 설정되어야 합니다.
가능한 값들:
min: 최소값max: 최대값mean: 평균값median: 중위값
--backdate <SECONDS>
선택사항: 보고서의 날짜를 과거로 변경합니다 (epoch 이후 초). 주의: 이는 과거 보고서의 순서에 영향을 줄 수 없습니다! 이는 프로젝트에 연대순서대로 역사적 데이터를 초기 씨딩할 때 유용합니다.
--allow-failure
선택사항: 벤치마크 테스트 실패를 허용합니다.
--format <FORMAT>
선택 사항: 최종 보고서의 형식.
기본 값은 human입니다.
가능한 값:
human: 사람이 읽을 수 있는 형식json: JSON 형식html: HTML 형식
--quiet
선택 사항: 조용한 모드, 최종 보고서만 출력합니다.
출력 형식을 변경하려면 --format 옵션을 사용하세요.
--github-actions <GITHUB_TOKEN>
선택 사항: GitHub API 인증 토큰을 설정하세요.
가장 편리한 방법은 GitHub Actions GITHUB_TOKEN 환경 변수를 사용하는 것입니다(예: --github-actions ${{ secrets.GITHUB_TOKEN }}).
이 옵션이 설정되고 GitHub Actions에서 bencher run이 사용될 경우,
결과가 Bencher Report (<프로젝트 이름>)이라는 이름의 GitHub Check로 헤드 커밋에 추가됩니다(--ci-id가 설정된 경우 Bencher Report (<ID>)).
따라서 동일한 커밋에 대한 서로 다른 프로젝트의 실행은 각각 고유한 GitHub Check를 갖게 됩니다.
경고가 생성되면 GitHub Check가 실패하므로, 브랜치 보호에서 필수 상태 검사로 사용할 수 있습니다.
프로젝트 이름을 변경하면 GitHub Check 이름도 변경되므로, 직접 관리하는 이름이 필요하면 --ci-id를 사용하세요.
GitHub Check는 벤치마크가 시작되기 전에 in_progress 상태로 생성되며, 벤치마크가 끝나면 결과와 함께 완료됩니다.
이를 위해서는 벤치마크가 시작되기 전에 프로젝트 이름을 확인해야 하며, 이는 --project가 설정되어 있고 프로젝트가 이미 존재하는 경우에만 가능합니다. 그렇지 않으면 진행 중인 GitHub Check의 이름은 결과가 게시될 때까지 Bencher Report가 됩니다.
결과가 게시되기 전에 bencher run이 오류로 종료되면 GitHub Check는 생성될 때의 이름을 유지한 채 실패로 표시됩니다.
이 경우 토큰에 write 권한을 가진 checks 범위가 필요합니다.
GitHub Check를 생성할 수 없는 경우, bencher run은 경고를 기록하고 계속 진행합니다.
bencher run이 pull request의 일부로 사용될 경우,
결과가 pull request에도 댓글로 추가됩니다.
이 경우 토큰에 write 권한을 가진 pull-requests 범위가 필요합니다.
결과는 항상 작업 요약에도 추가됩니다.
🐰 GitHub Action 내의 Docker 컨테이너 안에서 실행하는 경우, 다음 환경 변수를 전달하고
GITHUB_EVENT_PATH로 지정된 경로를 마운트해야 합니다:
GITHUB_ACTIONSGITHUB_EVENT_NAMEGITHUB_EVENT_PATHGITHUB_SHAGITHUB_API_URL(GitHub Enterprise Server 전용)
--ci-only-thresholds
선택 사항: 분기, 테스트베드 및 측정에 대한 기준점이 존재하는 경우에만 CI에 결과를 게시합니다. 기준점이 존재하지 않으면 pull request 댓글이 게시되지 않습니다. 이는 pull request 댓글에만 적용됩니다. GitHub Check는 항상 생성됩니다. 필요 조건: --github-actions
--ci-only-on-alert
선택 사항: 경고가 생성된 경우 에만 CI에 결과 게시를 시작합니다. 경고가 생성되면 그 이후의 모든 결과도 경고를 포함하지 않더라도 게시됩니다. 이는 pull request 댓글에만 적용됩니다. GitHub Check는 항상 생성됩니다. 필요 조건: --github-actions
--ci-id <ID>
선택 사항: CI에 결과를 게시하기 위한 사용자 정의 ID입니다. 기본적으로, Bencher는 프로젝트, 브랜치, 테스트베드 및 어댑터의 조합에 따라 결과를 자동으로 분리합니다. Bencher가 동일한 CI 워크플로우에서 동일한 프로젝트, 브랜치, 테스트베드 및 어댑터 조합으로 여러 번 실행될 때 사용자 정의 ID를 설정하는 것이 유용합니다. 이 ID는 GitHub Check 이름에서 프로젝트 이름 대신 사용되므로(예: Bencher Report (<ID>)), 각 호출이 별도의 필수 상태 검사로 사용할 수 있는 안정적인 이름을 갖게 됩니다. 필요 사항: --github-actions
--ci-number <NUMBER>
선택적: CI에 결과를 게시하기 위한 이슈 번호입니다.
Bencher는 결과를 게시하는 데 필요한 CI 이슈 번호를 자동으로 감지하려고 시도합니다.
하지만 GitHub Actions에서 workflow_run을 사용하는 복잡한 설정에서는 항상 가능한 것은 아닙니다.
필수 조건: --github-actions
--ci-public-links
선택적: 모든 링크를 로그인이 필요 없는 공개 URL로 설정합니다.
필수 조건: --github-actions
--shell <SHELL>
옵션: 쉘 명령어 경로.
기본값은 유닉스 계열 환경에서는 /bin/sh, 윈도우에서는 cmd입니다.
--flag <FLAG>
선택사항: 셸 명령어 플래그.
Unix 계열 환경에서는 기본값이 -c, Windows에서는 /C입니다.
--exec
선택 사항: 명령을 쉘 명령이 아닌 실행 가능한 명령으로 실행합니다.
bencher run에 대한 인수의 수가 하나보다 많은 경우 기본값입니다.
--host <URL>
선택 사항: 백엔드 호스트 URL. 기본값은 Bench Cloud 입니다: https://api.bencher.dev
--insecure-host
선택 사항: Bencher API 서버에 대한 안전하지 않은 연결을 허용합니다.
이 플래그는 자체 서명된 인증서나 시스템의 인증서 저장소에 포함되지 않은 인증서를 사용하는 Bencher 셀프 호스티드 인스턴스에 연결할 때 유용합니다. 이는 본질적으로 안전하지 않은 HTTP 연결에는 적용되지 않으며, HTTPS 연결에만 해당됩니다.
경고: SSL 검증을 우회하므로 --insecure-host는 반드시 확인된 소스와 안전한 네트워크에서만 사용하십시오. 그렇지 않으면 중간자 공격에 노출될 수 있습니다.
--native-tls
선택 사항: 플랫폼의 기본 인증서 저장소에서 TLS 인증서를 로드합니다.
기본적으로 bencher는 포함된 webpki-roots crate에서 인증서를 로드합니다. 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의 기본사항을 배웠습니다! 🎉