Bencher runner CLI

runner up

启动 runner，轮询并执行基准测试 Job。 这是用于操作 Self-Hosted Runner 的长时间运行命令。 runner 向 API 服务器打开单个 WebSocket 连接， 认领与其 Spec 匹配的 Job，执行它们，并将结果报告回去。 runner 以 JSON 格式将日志写入 stderr，每行一个对象，并且只以字节数记录 Job 的输出。

runner up [OPTIONS]

选项

--host <HOST>

要连接的 Bencher API 服务器。 默认使用 https://api.bencher.dev。 也可以通过 BENCHER_HOST 环境变量设置。

--runner <RUNNER>

要作为其运行的 Runner 的 UUID 或 slug。 也可以通过 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， 因此该目录只需为一个 jail 准备真实的容量。 设置 --image-cache-size 后，它还会保存 Image 缓存，最多到该大小。 无论状态目录如何，一台主机同一时间只运行一个 Runner： 以 root 身份启动的 Runner 在运行期间一直持有锁 /run/bencher/runner.lock， 以 root 身份启动的第二个 Runner 会立即退出，并报出指明该锁的错误；不以 root 身份运行的 Runner 无法打开该锁，会在没有锁的情况下运行。 以 root 身份启动的 Runner 在启动时以及每个沙箱 Job 之前，都会终止仍在 /sys/fs/cgroup/bencher 下的 cgroup 中运行的任何进程，例如在 Job 中途被终止的 Runner 留下的沙箱，无论该 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。 如果没有此标志，其 Spec 没有 Sandbox 的 Job 会在运行时被拒绝。 非沙箱化的 Job 直接在主机上运行，因此仅对受信任的工作负载启用此项。 也可以通过 BENCHER_DANGER_ALLOW_NO_SANDBOX 环境变量设置。

--sandbox-log-level <SANDBOX_LOG_LEVEL>

沙箱进程的日志级别。 默认使用 warning。

--no-raid-pause

在主机上的 md RAID 阵列执行重新同步、恢复、检查、修复或重塑时，继续接受 Job。 默认情况下，Runner 在请求每个 Job 之前检查其 md 阵列， 只要其中任何一个正在执行这些操作，Runner 就会暂停：在同步完成之前不接受新的 Job， 并且从不停止已经在运行的 Job。 暂停的 Runner 保持连接，并继续自我更新。

--no-auto-update

禁用来自服务器的自动更新。 默认情况下，当服务器提供新版本时，runner 会在 Job 之间自我更新。 也可以通过 BENCHER_NO_AUTO_UPDATE 环境变量设置。

--update-channel <UPDATE_CHANNEL>

自动更新使用的更新通道，stable 或 canary。 默认使用 stable。 stable 通道更新到版本化的发布版本。 canary 通道跟踪滚动 canary 构建， 每当 runner 在 Bencher Cloud 部署中发生变化时，该构建都会重新构建。 也可以通过 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 / 超线程和睿频加速（turbo boost）； 将 CPU 调频调速器（governor）设为 performance，swappiness 设为 10，perf_event_paranoid 设为 -1。 在自上次启动以来 runner 尚未调优过的主机上，下面的标志会改为将各项优化保持在其主机默认值。

主机调优会一直保留到主机重启：每项设置都是仅在运行时生效的写入，runner 退出时不会将其还原；C-state 保持除外，它会在 runner 退出时结束。 在一次调优运行之后，跳过其他任何设置的标志从下一次重启起生效：在此之前，该设置保持其调优值，runner 会在启动时记录该值。 移除 runner 后，请重启共享主机。

--no-tuning

禁用所有主机调优优化。

--aslr

不禁用 ASLR（默认：基准测试时禁用）。

--nmi-watchdog

不禁用 NMI 看门狗（默认：基准测试时禁用）。

--smt

不禁用 SMT / 超线程（默认：基准测试时禁用）。

--turbo

不禁用睿频加速（默认：基准测试时禁用）。

--numa-balancing

不禁用自动 NUMA 平衡（默认：基准测试时禁用）。

--timer-migration

不禁用定时器迁移（默认：基准测试时禁用）。

--soft-watchdog

不禁用软锁死（soft lockup）看门狗（默认：基准测试时禁用）。

--ksm

不禁用内核同页合并 KSM（默认：基准测试时禁用）。

--cstates

不禁用深度 C-state（默认：基准测试时禁用）。

--no-irq-steering

不将设备 IRQ 和内核工作队列引导到内务（housekeeping）核心。

--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，并在本地主机上执行一次。 与 runner up 不同，它不会连接到 API 服务器，也不认领 Job。 它直接运行单个 Image，这对于在提交真实 Job 之前测试和调试 Runner 主机 或 Image 很有用。 Image 的输出原样发送到 stdout 和 stderr，runner 自身的日志则以 JSON 格式写入 stderr，每行一个对象。

runner run --image <IMAGE> [OPTIONS]

选项

--image <IMAGE>

要运行的 OCI Image，以本地路径或注册表引用的形式给出。

--token <TOKEN>

拉取 Image 时用于注册表认证的 JWT 令牌。

--sandbox <SANDBOX>

基准测试执行的沙箱模式。 使用 firecracker 表示 Firecracker microVM（仅限 Linux）。 省略表示非沙箱化的主机执行。

--timeout <TIMEOUT>

从运行开始起由所有迭代共享的执行超时（秒）。 默认使用 300。

--state-dir <STATE_DIR>

Runner 的持久状态目录。 必须是绝对路径。 限制沙箱的 jail 在该目录下创建， 非正常退出遗留的 jail 会在每个沙箱 Job 运行前从中清除。 每个 jail 都保存着完整的客户机根文件系统和一份 microVM 二进制文件副本， 而 Runner 一次只运行一个 Job， 因此该目录只需为一个 jail 准备真实的容量。 无论状态目录如何，一台主机同一时间只运行一个 Runner： 以 root 身份启动的 Runner 在运行期间一直持有锁 /run/bencher/runner.lock， 以 root 身份启动的第二个 Runner 会立即退出，并报出指明该锁的错误；不以 root 身份运行的 Runner 无法打开该锁，会在没有锁的情况下运行。 以 root 身份启动的 Runner 在启动时以及每个沙箱 Job 之前，都会终止仍在 /sys/fs/cgroup/bencher 下的 cgroup 中运行的任何进程，例如在 Job 中途被终止的 Runner 留下的沙箱，无论该 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>

guest 内部要收集的输出文件路径。 可以多次指定。

--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 / 超线程和睿频加速（turbo boost）； 将 CPU 调频调速器（governor）设为 performance，swappiness 设为 10，perf_event_paranoid 设为 -1。 在自上次启动以来 runner 尚未调优过的主机上，下面的标志会改为将各项优化保持在其主机默认值。

主机调优会一直保留到主机重启：每项设置都是仅在运行时生效的写入，runner 退出时不会将其还原；C-state 保持除外，它会在 runner 退出时结束。 在一次调优运行之后，跳过其他任何设置的标志从下一次重启起生效：在此之前，该设置保持其调优值，runner 会在启动时记录该值。 移除 runner 后，请重启共享主机。

--no-tuning

禁用所有主机调优优化。

--aslr

不禁用 ASLR（默认：基准测试时禁用）。

--nmi-watchdog

不禁用 NMI 看门狗（默认：基准测试时禁用）。

--smt

不禁用 SMT / 超线程（默认：基准测试时禁用）。

--turbo

不禁用睿频加速（默认：基准测试时禁用）。

--numa-balancing

不禁用自动 NUMA 平衡（默认：基准测试时禁用）。

--timer-migration

不禁用定时器迁移（默认：基准测试时禁用）。

--soft-watchdog

不禁用软锁死（soft lockup）看门狗（默认：基准测试时禁用）。

--ksm

不禁用内核同页合并 KSM（默认：基准测试时禁用）。

--cstates

不禁用深度 C-state（默认：基准测试时禁用）。

--no-irq-steering

不将设备 IRQ 和内核工作队列引导到内务（housekeeping）核心。

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

打印帮助。