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
にパイプすることができます。
オプション
--project <PROJECT>
--project
オプションまたはBENCHER_PROJECT
環境変数のどちらかを
既存のプロジェクトのスラグまたはUUIDに設定する必要があります。
両方が定義されている場合、--project
オプションはBENCHER_PROJECT
環境変数に優先します。
--token <TOKEN>
--token
オプションまたはBENCHER_API_TOKEN
環境変数のどちらかを有効なAPIトークンに設定する必要があります。
両方が定義されている場合、--token
オプションはBENCHER_API_TOKEN
環境変数に優先します。
--branch <BRANCH>
--branch-start-point <BRANCH>
--branch-start-point-hash <HASH>
--branch-reset
完全な概要については、branch selectionを参照してください。
--hash <HASH>
オプション:40文字のSHA-1コミットハッシュ。 2つのレポートが同じブランチとハッシュを持っている場合、それらは同じコミットから来たものと見なされます。 したがって、それらは同じブランチバージョン番号を持つでしょう。
提供されない場合、Bencher CLIは現在のgitハッシュを見つけようとします。 最初に、現在の作業ディレクトリでgitリポジトリを探します。 見つからない場合、親ディレクトリに移動してルートディレクトリまで再試行を続けます。 gitリポジトリが見つかった場合、現在のブランチのHEAD gitハッシュが使用されます。
--no-hash
任意: git
コミットハッシュを探さないようにします。
このオプションは--hash
と競合し、
git
リポジトリを検索するそのデフォルトの動作を上書きします。
--testbed <TESTBED>
オプション:--testbed
オプションまたはBENCHER_TESTBED
環境変数のいずれかを既存のテストベッドのスラグまたはUUIDに設定することができます。
両方が定義されている場合、--testbed
オプションはBENCHER_TESTBED
環境変数に優先します。
どちらも定義されていない場合、デフォルトのテストベッドとしてlocalhost
が使用されます。
--adapter <ADAPTER>
--average <AVERAGE>
--file <FILE>
--file-size <FILE>
完全な概要については、benchmark harness adapterを参照してください。
--iter <ITER>
オプション:実行繰り返し数。デフォルトは1
です。
--fold <FOLD>
オプション:複数の結果を一つの結果にまとめます。
必要条件:--iter
が設定されていること。
可能な値:
min
: 最小値max
: 最大値mean
: 値の平均median
: 値の中央値
--backdate <DATETIME_SECONDS>
オプション:レポートのバックデート(エポックからの秒数)。 注:これは過去のレポートの並べ替えに影響を及ぼしません! これは、プロジェクトに初めて歴史的データを_時系列_順にシーディングする際に便利です。
--allow-failure
オプション:ベンチマークテストの失敗を許可する。
--err
オプション:アラートが生成されたときにエラーになります。完全な概要については、thresholds and alertsを参照してください。
--format <FORMAT>
オプション: 最終レポートのフォーマット。
デフォルトは human
です。
考えられる値:
human
: 人間が読む形式json
: JSON形式html
: HTML形式
--quiet
オプション: レポートの最終結果のみを出力する簡易モードです。
出力形式を変更するには、こちらの --format
オプションを使用してください。
--github-actions <GITHUB_TOKEN>
オプション:GitHub API認証トークンを設定します(例 --github-actions ${{ secrets.GITHUB_TOKEN }}
)。
このオプションが設定されていて、bencher run
がプルリクエストの一部としてGitHub Actionsで使用される場合、
結果はプルリクエストにコメントとして追加されます。
これを行う最も便利な方法は、GitHub ActionsのGITHUB_TOKEN
環境変数です。
🐰 GitHub Actionの中でDockerコンテナ内で実行している場合、次の環境変数を渡し、
GITHUB_EVENT_PATH
で指定されたパスをマウントする必要があります:
GITHUB_ACTIONS
GITHUB_EVENT_NAME
GITHUB_EVENT_PATH
--ci-only-thresholds
オプション:メトリックの種類、ブランチ、テストベッドに対するThresholdが存在する場合にのみ、結果をCIに投稿します。Thresholdが存在しない場合、何も投稿されません。
--github-actions
が必要です。
--ci-only-on-alert
オプション:Alertが生成された場合にのみ、結果の投稿をCIに開始します。
Alertが生成されると、その後の結果もアラートが含まれていなくても投稿されます。
--github-actions
が必要です。
--ci-id
オプション:CIに結果を投稿するためのカスタムID。
デフォルトでは、Bencherはプロジェクト、ブランチ、テストベッド、Adapterの組み合わせによって自動的に結果を分割します。
同じプロジェクト、ブランチ、テストベッド、アダプタの組み合わせでBencherを同じCIワークフローで複数回実行するときに、カスタムIDを設定することは便利です。
--github-actions
が必要です。
--ci-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。デフォルトはhttps://api.bencher.devです。
--attempts <ATTEMPTS>
オプション:最大リクエスト再試行回数。デフォルトは10
回です。
--retry-after <RETRY_AFTER_SECONDS>
オプション:指定した秒数後にリクエストを再試行します (指数関数的バックオフ)。デフォルトは1
秒です。
--dry-run
オプション:ドライランを実行します。これはバックエンドに何もデータを保存しません。 branch selectionで詳述されるレポートやブランチは作成されません。
-h
--help
オプション:ヘルプを表示します。
🐰 おめでとう!
bencher run
の基本を学びました!🎉