systemslab experiment monitor

Description	Block until an experiment reaches a terminal state, printing a line each time one of its jobs finishes.
Usage	systemslab experiment monitor [OPTIONS] <UUID>

Description

The systemslab experiment monitor command waits for an experiment to reach a terminal state instead of requiring a script to poll systemslab experiment show in a loop. As each job finishes, it prints a line such as:

job loadgen: complete

When the experiment itself reaches a terminal state, it prints a final summary line and exits:

Experiment my-benchmark (018f9c57-...): success

The terminal states are:

State	Meaning
success	Every job in the experiment succeeded.
failure	A step in one of the jobs exited with an error.
error	An internal SystemsLab error, not a failure of the workload under test.
cancelled	The experiment was cancelled.
timeout	The experiment was queued too long without being scheduled.

The command exits 0 only if the experiment's final state is success. Any other terminal state, or the --timeout deadline elapsing first, causes it to exit non-zero -- so it can be used directly to gate a script:

ID=$(systemslab submit experiment.jsonnet)
systemslab experiment monitor "$ID" && echo "benchmark passed"

On a real terminal failure the Experiment ... summary line above is still printed to stdout before the non-zero exit, so a script can tell that outcome apart from a --timeout giveup, which instead prints a "timed out" error to stderr and no summary line (the experiment is still running -- run the command again to keep waiting).

Rather than polling on a timer, this subscribes to the same server-push channel the web UI uses and only re-checks the experiment when the server reports that it may have changed.

Options

Option	Default	Description
<UUID>		The experiment ID.
--timeout <TIMEOUT>	Wait indefinitely	Give up and exit non-zero if the experiment has not reached a terminal state within this many seconds. The experiment itself keeps running on the server -- only this command's wait gives up, and it can be run again to keep waiting.

Common Options

Option	Default	Description
--systemslab-url		The URL at which to access the systemslab server.
--color	auto	Controls when color is used in the output. Possible values are auto, always, and never.
--output-format	long	Output format to use when outputting messages. long will result output designed to be human-readable while short is short output meant to be used within scripts.

Environment Variables

Variable	Description
SYSTEMSLAB_URL	Specify the URL used to contact the SystemsLab server. Equivalent to --systemslab-url.