bencher run CLI サブコマンド
bencher runは最も人気のあるCLIサブコマンドです。
これはベンチマークを実行し、結果を報告するために使用されます。
したがって、それは最も複雑なサブコマンドの一つです。
このページでは、bencher runに渡すことができるオプション、フラグ、引数を説明します。
bencher run [OPTIONS] [COMMAND] [ARGUMENTS...]ベンチマークコマンド
bencher runへの最初の引数は、オプションのベンチマークコマンドです。
これは実行されるコマンドで、ベンチマークハーネスを呼び出します。
BENCHER_CMD環境変数を使用して設定することもできます。
デフォルトではこのコマンドはシェルで実行され、--shell オプションと --flag オプションで設定することができます。
その出力はベンチマークハーネスアダプターによって解析され、--adapter オプションを使用して設定します。
しかし、ベンチマークハーネスがファイルに出力する場合は、出力ファイルのパスを指定するためにも--file オプションを使用しなければなりません。
出力ファイルのサイズ（つまりバイナリサイズ）をその内容の代わりに追跡するためには、出力ファイルのパスを指定する--file-size オプションを使用します。
コマンドをシェルで実行したくない場合は、--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 オプションのいずれも指定されていない場合、bencher runは代わりに stdin から読み取ります。
これにより、他のコマンドの出力をファイルに保存するか、bencher runにパイプすることができます。
Options
--project <PROJECT>
オプション: --project オプションまたは BENCHER_PROJECT 環境変数のいずれかを、プロジェクトのスラグまたはUUIDとして設定できます。指定された値がスラグで、プロジェクトがまだ存在しない場合は、自動的に作成されます。ただし、指定された値がUUIDの場合、プロジェクトはすでに存在している必要があります。両方が指定された場合、--project オプションが BENCHER_PROJECT 環境変数より優先されます。どちらも指定されない場合、次の方法でプロジェクトのスラグが生成されます:
- 使用可能な場合、
gitリポジトリの親ディレクトリの名前。 - 使用可能な場合、
gitリポジトリの初回コミットの7桁の16進短縮ハッシュ。 - サポートされているオペレーティングシステムに基づく、ローカルマシンの13桁の英数字フィンガープリント。
例えば、生成されたプロジェクトのスラグは次のようになります: project-abc4567-wxyz123456789
新しいプロジェクトが作成された場合、スラグが指定されるか生成されるかに関わらず、プロジェクトは必ずいずれかの組織に所属しなければなりません。ユーザーが認証済みの場合、そのユーザーの個人用組織にプロジェクトが追加されます。ユーザーが認証されていない場合、プロジェクトは新しい unclaimed 組織の下に作成されます。この組織は、プロジェクトの公開されたPerfページから claimed するか、後の bencher run の呼び出しでユーザーが認証されている間にプロジェクトのスラグを使用して claimed できます。
--token <TOKEN>
オプション: --token オプションまたは BENCHER_API_TOKEN 環境変数のいずれかを設定して、有効な API トークンを指定できます。
両方が指定されている場合、--token オプションが BENCHER_API_TOKEN 環境変数よりも優先されます。
どちらも指定されていない場合、プロジェクトは unclaimed でなければなりません。
つまり、すでにプロジェクトを claimed している場合、有効な 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>
完全な概要については、benchmark harness adapterを参照してください。
--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>
オプション: GitHub API認証トークンを設定します。
これを行う最も便利な方法は、GitHub Actions GITHUB_TOKEN 環境変数を使用することです（例：--github-actions ${{ secrets.GITHUB_TOKEN }}）。
このオプションが設定され、GitHub Actions内でbencher runがプルリクエストの一部として使用されると、結果はコメントとしてプルリクエストに追加されます。
これにはトークンがpull-requests スコープに対するwrite権限を持っている必要があります。
そうでなければ、結果はコミットに対するGitHubチェックとして追加されます。
これにはトークンがchecks スコープに対するwrite権限を持っている必要があります。
いずれの場合でも、結果はジョブサマリーにも追加されます。
🐰 GitHub Action内でDockerコンテナを実行している場合、以下の環境変数を渡し、
GITHUB_EVENT_PATHで指定されたパスをマウントする必要があります：
GITHUB_ACTIONSGITHUB_EVENT_NAMEGITHUB_EVENT_PATHGITHUB_SHAGITHUB_API_URL(GitHub Enterprise Server のみ)
--ci-only-thresholds
オプション: しきい値が存在するブランチ、テストベッド、および測定のためのCIのみに結果を投稿します。
しきい値が存在しない場合は、何も投稿されません。
必要条件: --github-actions
--ci-only-on-alert
任意: アラートが生成された場合にのみCIに結果を投稿します。
アラートが生成されると、その後のすべての結果もアラートが含まれていなくても投稿されます。
必要条件: --github-actions
--ci-id <ID>
オプション: CIに結果を投稿するためのカスタムID。
デフォルトでは、Bencherは結果をプロジェクト、ブランチ、テストベッド、およびアダプターの組み合わせで自動的に区切ります。
同じプロジェクト、ブランチ、テストベッド、アダプターの組み合わせで、同じCIワークフロー内でBencherを複数回実行する場合にカスタムIDを設定することが有用です。
必要条件: --github-actions
--ci-number <NUMBER>
オプション: CIに結果を投稿するための課題番号。
BencherはCI結果を投稿するために必要な課題番号を自動検出しようとします。
ただし、GitHub Actionsでworkflow_runを使用するような複雑な設定では、必ずしも利用できるとは限りません。
必要条件: --github-actions
--shell <SHELL>
オプション: シェルコマンドパス。
Unix系環境ではデフォルトは /bin/sh、Windowsでは cmd です。
--flag <FLAG>
オプション: シェルコマンドのフラグ。 Unix系環境ではデフォルトで -c が使用され、Windowsでは /C が使用されます。
--exec
オプション: シェルコマンドではなく、実行可能なコマンドとして実行します。
bencher runへの引数の数が1つ以上の場合のデフォルトです。
--host <URL>
オプション: バックエンドホストのURL。 デフォルトはBench Cloud: https://api.bencher.dev
--insecure-host
オプション: Bencher API サーバーへの安全でない接続を許可します。
このフラグは、自己署名証明書やシステムの証明書ストアに含まれていない証明書を使用する、Bencher Self-Hosted インスタンスに接続する際に便利です。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の基本を学びました！🎉