Bencher runner CLI

runner up

Runner を起動し、ベンチマーク Job をポーリングして実行します。 これは セルフホスト型 Runner を運用するために使う、長時間実行コマンドです。 Runner は API サーバーへの単一の WebSocket 接続 を開き、 自身の Spec に一致する Job を要求し、それらを実行して結果を報告します。 Runner は自身のログを 1 行に 1 つのオブジェクトとして JSON 形式で stderr に書き込み、Job の出力はバイト数としてのみ記録します。

runner up [OPTIONS]

オプション

--host <HOST>

接続先の Bencher API サーバー。 デフォルトでは https://api.bencher.dev が使用されます。 BENCHER_HOST 環境変数でも設定できます。

--runner <RUNNER>

運用する Runner の UUID またはスラッグ。 BENCHER_RUNNER 環境変数でも設定できます。

--key <KEY>

Runner が作成された ときに返された Runner 認証キー (bencher_runner_...)。 BENCHER_RUNNER_KEY 環境変数でも設定できます。

--poll-timeout <POLL_TIMEOUT>

Job を待機する際のロングポーリングのタイムアウト (秒)。1 から 900 の範囲です。 デフォルトでは 55 が使用されます。

--state-dir <STATE_DIR>

Runner の永続的な状態ディレクトリ。 絶対パスである必要があります。 サンドボックスを閉じ込める jail はこのディレクトリの下に作成され、 異常終了で残った jail は、各サンドボックス Job の実行前にここから一掃されます。 各 jail はゲストのルートファイルシステム全体と microVM バイナリのコピーを保持し、 Runner は Job を一度に 1 つずつ実行するため、 このディレクトリには jail 1 つ分の実容量が必要です。 --image-cache-size を指定すると、そのサイズまで Image キャッシュも保持します。 状態ディレクトリにかかわらず、1 つのホストで実行できる Runner は一度に 1 つだけです。 root として起動した Runner は実行中ずっとロック /run/bencher/runner.lock を保持し、 root として起動した 2 つ目の Runner はそのロックを示すエラーを出して即座に終了します。root 以外の Runner はロックを開けないため、ロックなしで実行されます。 root として起動した Runner は、起動時と各サンドボックス Job の前に、Job の途中で強制終了された Runner のサンドボックスなど、/sys/fs/cgroup/bencher の下の cgroup でまだ実行中のプロセスを、その Runner の状態ディレクトリにかかわらずすべて終了させます。 専用のファイルシステムまたは tmpfs マウントがサポートされており、推奨されます。 書き込み負荷をシステムディスクから切り離せます。 作成したばかりのファイルシステムは lost+found ディレクトリを含んでいても受け付けられます。 このファイルシステムは nodev や noexec でマウントされていてはなりません。/tmp、/dev/shm、/run はよくそのようにマウントされているため、tmpfs を使う場合はこれらのオプションなしで専用にマウントしてください。 状態ディレクトリ自体を、そのようなファイルシステムを指す root 所有のシンボリックリンクにすることもできます。 たとえば /var/lib/bencher-runner を専用ディスクに向ける形です。 リンクがたどられるのは、リンクを含むディレクトリに書き込めるのが root だけで、 リンクが最終的なターゲットを直接指しており、 そのターゲットが root だけが書き込めるパス上に既に存在する場合に限られます。 ターゲットがまだ存在しないリンクは拒否されるため、先にターゲットを作成してください。 デフォルトでは /var/lib/bencher-runner が使用されます。 環境変数 BENCHER_STATE_DIR でも設定できます。

--jail-uid <JAIL_UID>

サンドボックスプロセスが移行する非特権ユーザー ID。 デフォルトでは 61016 が使用されます。 0 は指定できません。 このユーザー ID を所有するホスト上のプロセスはサンドボックスにシグナルを送れるため、 ホストが他の用途に割り当てていない ID を指定してください。 環境変数 BENCHER_JAIL_UID でも設定できます。

--jail-gid <JAIL_GID>

サンドボックスプロセスが移行する非特権グループ ID。 デフォルトでは 61016 が使用されます。 0 は指定できません。 環境変数 BENCHER_JAIL_GID でも設定できます。

--danger-allow-no-sandbox

Sandbox なしでの Job の実行を許可します。 このフラグがない場合、Sandbox を持たない Spec の Job は実行時に拒否されます。 サンドボックスなしの Job はホスト上で直接実行されるため、信頼できるワークロードに対してのみ有効にしてください。 BENCHER_DANGER_ALLOW_NO_SANDBOX 環境変数でも設定できます。

--sandbox-log-level <SANDBOX_LOG_LEVEL>

サンドボックスプロセスのログレベル。 デフォルトでは warning が使用されます。

--no-raid-pause

ホスト上の md RAID アレイが再同期、復旧、チェック、修復、または再形成を行っている間も Job を受け付け続けます。 デフォルトでは、Runner は各 Job を要求する前に md アレイを確認し、 いずれかがこれらの処理を実行している間は一時停止します。同期が完了するまで新しい Job を受け付けず、 すでに実行中の Job を停止することはありません。 一時停止中の Runner は接続を維持し、自己更新も引き続き行います。

--no-auto-update

サーバーからの自動更新を無効にします。 デフォルトでは、サーバーが新しいバージョンを提供すると、Runner は Job の合間に自身を更新します。 BENCHER_NO_AUTO_UPDATE 環境変数でも設定できます。

--update-channel <UPDATE_CHANNEL>

自動更新に使用する更新チャネル。stable または canary のいずれかです。 デフォルトでは stable が使用されます。 stable チャネルはバージョン付きリリースへ更新します。 canary チャネルはローリング canary ビルドを追跡し、 このビルドは Bencher Cloud のデプロイで Runner が変更されるたびに再ビルドされます。 BENCHER_UPDATE_CHANNEL 環境変数でも設定できます。 --no-auto-update と競合します。

--max-download-size <MAX_DOWNLOAD_SIZE>

自己更新バイナリの最大ダウンロードサイズ (バイト)。 デフォルトでは 500 MiB が使用されます。 --no-auto-update と競合します。

--image-cache-size <IMAGE_CACHE_SIZE>

Runner が Job をまたいで保持する Image blob の最大サイズ (バイト)。 Runner はプルした各 Image の config と layer の blob を --state-dir 配下の blobs に保持するため、 Job は Runner がまだ保持していない blob だけをダウンロードしますが、 Image のマニフェストは毎回レジストリから取得します。 Job の合間に、Runner は残りがこのサイズに収まるまで、最も長く使われていない blob から削除します。 Runner は起動時にこのストアを作成して自身のものにし、それができない場合はディレクトリを示すエラーとともにすぐに終了します。 デフォルト、または 0 では、Runner は Job をまたいで blob を保持せず、以前に保持していた blob を削除します。 環境変数 BENCHER_IMAGE_CACHE_SIZE でも設定できます。

--max-output-size <MAX_OUTPUT_SIZE>

収集される stdout と stderr の最大サイズ (バイト)。 デフォルトでは 25 MiB が使用されます。

--max-file-count <MAX_FILE_COUNT>

デコードする出力ファイルの最大数。 デフォルトでは 255 が使用されます。

--max-symlinks <MAX_SYMLINKS>

パス解決時にたどるシンボリックリンクの最大数。 Linux カーネルの MAXSYMLINKS 制限に一致します。 デフォルトでは 40 が使用されます。 サンドボックスなしモードでのみ使用されます。

ホストチューニング

各ベンチマークの前に、runner は測定ノイズを低減するためにホストチューニングを適用します。 デフォルトでは、ASLR、NMI ウォッチドッグ、SMT / ハイパースレッディング、ターボブーストを無効にし、 CPU スケーリングガバナーを performance、swappiness を 10、perf_event_paranoid を -1 に設定します。 前回の起動以降に runner がチューニングしていないホストでは、以下のフラグは、個々の最適化を無効にせず、ホストのデフォルト値のまま維持します。

ホストチューニングはホストが再起動するまで持続します。各設定は実行時のみの書き込みであり、runner は終了時にそれを元に戻しません。ただし、C ステートの保持は runner の終了時に解除されます。 チューニングを行った実行の後では、それ以外の設定をスキップするフラグは次回の再起動から有効になります。それまでは、その設定はチューニングされた値のままであり、runner は起動時にその値をログに出力します。 共有ホストでは、runner を削除した後にホストを再起動してください。

--no-tuning

すべてのホストチューニング最適化を無効にします。

--aslr

ASLR を無効にしません (デフォルト: ベンチマークでは無効)。

--nmi-watchdog

NMI ウォッチドッグを無効にしません (デフォルト: ベンチマークでは無効)。

--smt

SMT / ハイパースレッディングを無効にしません (デフォルト: ベンチマークでは無効)。

--turbo

ターボブーストを無効にしません (デフォルト: ベンチマークでは無効)。

--numa-balancing

自動 NUMA バランシングを無効にしません (デフォルト: ベンチマークでは無効)。

--timer-migration

タイマーマイグレーションを無効にしません (デフォルト: ベンチマークでは無効)。

--soft-watchdog

ソフトロックアップウォッチドッグを無効にしません (デフォルト: ベンチマークでは無効)。

--ksm

KSM (Kernel Samepage Merging) を無効にしません (デフォルト: ベンチマークでは無効)。

--cstates

深い C ステートを無効にしません (デフォルト: ベンチマークでは無効)。

--no-irq-steering

デバイスの IRQ とカーネルのワークキューをハウスキーピングコアに振り向けません。

--no-cpuset-partition

分離された cpuset パーティションによってベンチマークコアをスケジューラーから切り離しません。

--swappiness <SWAPPINESS>

swappiness の値を設定します。 デフォルトでは 10 が使用されます。

--governor <GOVERNOR>

CPU スケーリングガバナーを設定します。 デフォルトでは performance が使用されます。

--perf-event-paranoid <PERF_EVENT_PARANOID>

perf_event_paranoid の値を設定します。 デフォルトでは -1 が使用されます。

--thp <THP>

ホストの Transparent Hugepage モードを never、madvise、always、leave のいずれかに設定します。 leave を指定すると、ホストの現在のモードを維持します。 デフォルトでは never が使用されます。

--help

ヘルプを表示します。

runner run

Image をプルし、rootfs を作成して、ローカルホスト上で 1 回だけ実行します。 runner up とは異なり、これは API サーバーに接続したり Job を要求したりしません。 単一の Image を直接実行するもので、実際の Job を送信する前に Runner ホストや Image を テスト・デバッグするのに役立ちます。 Image の出力はそのまま stdout と stderr に送られ、Runner 自身のログは 1 行に 1 つのオブジェクトとして JSON 形式で stderr に送られます。

runner run --image <IMAGE> [OPTIONS]

オプション

--image <IMAGE>

実行する OCI Image。ローカルパスまたはレジストリ参照として指定します。

--token <TOKEN>

Image をプルする際の、レジストリ認証用の JWT トークン。

--sandbox <SANDBOX>

ベンチマーク実行のサンドボックスモード。 Firecracker microVM には firecracker を使用します (Linux のみ)。 サンドボックスなしのホスト実行の場合は省略します。

--timeout <TIMEOUT>

実行の開始からすべての反復で共有される実行タイムアウト (秒)。 デフォルトでは 300 が使用されます。

--state-dir <STATE_DIR>

Runner の永続的な状態ディレクトリ。 絶対パスである必要があります。 サンドボックスを閉じ込める jail はこのディレクトリの下に作成され、 異常終了で残った jail は、各サンドボックス Job の実行前にここから一掃されます。 各 jail はゲストのルートファイルシステム全体と microVM バイナリのコピーを保持し、 Runner は Job を一度に 1 つずつ実行するため、 このディレクトリには jail 1 つ分の実容量が必要です。 状態ディレクトリにかかわらず、1 つのホストで実行できる Runner は一度に 1 つだけです。 root として起動した Runner は実行中ずっとロック /run/bencher/runner.lock を保持し、 root として起動した 2 つ目の Runner はそのロックを示すエラーを出して即座に終了します。root 以外の Runner はロックを開けないため、ロックなしで実行されます。 root として起動した Runner は、起動時と各サンドボックス Job の前に、Job の途中で強制終了された Runner のサンドボックスなど、/sys/fs/cgroup/bencher の下の cgroup でまだ実行中のプロセスを、その Runner の状態ディレクトリにかかわらずすべて終了させます。 専用のファイルシステムまたは tmpfs マウントがサポートされており、推奨されます。 書き込み負荷をシステムディスクから切り離せます。 作成したばかりのファイルシステムは lost+found ディレクトリを含んでいても受け付けられます。 このファイルシステムは nodev や noexec でマウントされていてはなりません。/tmp、/dev/shm、/run はよくそのようにマウントされているため、tmpfs を使う場合はこれらのオプションなしで専用にマウントしてください。 状態ディレクトリ自体を、そのようなファイルシステムを指す root 所有のシンボリックリンクにすることもできます。 たとえば /var/lib/bencher-runner を専用ディスクに向ける形です。 リンクがたどられるのは、リンクを含むディレクトリに書き込めるのが root だけで、 リンクが最終的なターゲットを直接指しており、 そのターゲットが root だけが書き込めるパス上に既に存在する場合に限られます。 ターゲットがまだ存在しないリンクは拒否されるため、先にターゲットを作成してください。 デフォルトでは /var/lib/bencher-runner が使用されます。 環境変数 BENCHER_STATE_DIR でも設定できます。

--jail-uid <JAIL_UID>

サンドボックスプロセスが移行する非特権ユーザー ID。 デフォルトでは 61016 が使用されます。 0 は指定できません。 このユーザー ID を所有するホスト上のプロセスはサンドボックスにシグナルを送れるため、 ホストが他の用途に割り当てていない ID を指定してください。 環境変数 BENCHER_JAIL_UID でも設定できます。

--jail-gid <JAIL_GID>

サンドボックスプロセスが移行する非特権グループ ID。 デフォルトでは 61016 が使用されます。 0 は指定できません。 環境変数 BENCHER_JAIL_GID でも設定できます。

--iter <ITER>

実行するベンチマークの反復回数。 デフォルトでは 1 が使用されます。

--allow-failure

ベンチマークの失敗が発生しても、残りの反復を打ち切らずに許可します。 時間切れになった場合は、それでも実行がタイムアウトとして終了します。 Image をプルまたは準備できない場合も、実行は終了します。

--entrypoint <ENTRYPOINT>

コンテナのエントリーポイントを上書きします。 複数回指定できます。

--cmd <CMD>

コンテナのコマンドを上書きします。 複数回指定できます。

--env <ENV>

環境変数を KEY=VALUE 形式で設定します。 複数回指定できます。

--network

VM 内でのネットワークアクセスを有効にします。

--output <OUTPUT>

収集するゲスト内の出力ファイルパス。 複数回指定できます。

--vcpus <VCPUS>

vCPU 数を上書きします (テスト用)。

--memory <MEMORY>

メモリ (MiB) を上書きします (テスト用)。

--disk <DISK>

ディスクサイズ (MiB) を上書きします (テスト用)。

--max-output-size <MAX_OUTPUT_SIZE>

収集される stdout と stderr の最大サイズ (バイト)。 デフォルトでは 25 MiB が使用されます。

--max-file-count <MAX_FILE_COUNT>

デコードする出力ファイルの最大数。 デフォルトでは 255 が使用されます。

--max-symlinks <MAX_SYMLINKS>

パス解決時にたどるシンボリックリンクの最大数。 Linux カーネルの MAXSYMLINKS 制限に一致します。 デフォルトでは 40 が使用されます。 サンドボックスなしモードでのみ使用されるため、--sandbox と競合します。

--sandbox-log-level <SANDBOX_LOG_LEVEL>

サンドボックスプロセスのログレベル。 --sandbox が必要です。 デフォルトでは warning が使用されます。

ホストチューニング

各ベンチマークの前に、runner は測定ノイズを低減するためにホストチューニングを適用します。 デフォルトでは、ASLR、NMI ウォッチドッグ、SMT / ハイパースレッディング、ターボブーストを無効にし、 CPU スケーリングガバナーを performance、swappiness を 10、perf_event_paranoid を -1 に設定します。 前回の起動以降に runner がチューニングしていないホストでは、以下のフラグは、個々の最適化を無効にせず、ホストのデフォルト値のまま維持します。

ホストチューニングはホストが再起動するまで持続します。各設定は実行時のみの書き込みであり、runner は終了時にそれを元に戻しません。ただし、C ステートの保持は runner の終了時に解除されます。 チューニングを行った実行の後では、それ以外の設定をスキップするフラグは次回の再起動から有効になります。それまでは、その設定はチューニングされた値のままであり、runner は起動時にその値をログに出力します。 共有ホストでは、runner を削除した後にホストを再起動してください。

--no-tuning

すべてのホストチューニング最適化を無効にします。

--aslr

ASLR を無効にしません (デフォルト: ベンチマークでは無効)。

--nmi-watchdog

NMI ウォッチドッグを無効にしません (デフォルト: ベンチマークでは無効)。

--smt

SMT / ハイパースレッディングを無効にしません (デフォルト: ベンチマークでは無効)。

--turbo

ターボブーストを無効にしません (デフォルト: ベンチマークでは無効)。

--numa-balancing

自動 NUMA バランシングを無効にしません (デフォルト: ベンチマークでは無効)。

--timer-migration

タイマーマイグレーションを無効にしません (デフォルト: ベンチマークでは無効)。

--soft-watchdog

ソフトロックアップウォッチドッグを無効にしません (デフォルト: ベンチマークでは無効)。

--ksm

KSM (Kernel Samepage Merging) を無効にしません (デフォルト: ベンチマークでは無効)。

--cstates

深い C ステートを無効にしません (デフォルト: ベンチマークでは無効)。

--no-irq-steering

デバイスの IRQ とカーネルのワークキューをハウスキーピングコアに振り向けません。

--no-cpuset-partition

分離された cpuset パーティションによってベンチマークコアをスケジューラーから切り離しません。

--swappiness <SWAPPINESS>

swappiness の値を設定します。 デフォルトでは 10 が使用されます。

--governor <GOVERNOR>

CPU スケーリングガバナーを設定します。 デフォルトでは performance が使用されます。

--perf-event-paranoid <PERF_EVENT_PARANOID>

perf_event_paranoid の値を設定します。 デフォルトでは -1 が使用されます。

--thp <THP>

ホストの Transparent Hugepage モードを never、madvise、always、leave のいずれかに設定します。 leave を指定すると、ホストの現在のモードを維持します。 デフォルトでは never が使用されます。

--help

ヘルプを表示します。