SystemsLab Experiment Specification

This page documents the systemslab experiment specification format. This is the format that is accepted by systemslab submit command as well as the /api/v1/submit API endpoint.

The schema here describes the fully expanded experiment specification. In practice, you will likely be writing a jsonnet file that evaluates to such a specification. Or, alternatively, you may write it out in json yourself.

name

This is a name for the experiment. It will be used to name the experiment in various SystemsLab webpages as well as when downloading artifacts.

metadata

Arbitrary user-provided metadata for this experiment.

This field will not be interpreted by SystemsLab and can instead be used to store whatever data you want for future use.

At the top-level this must be a JSON object but the values contained within that object can be any arbitrary JSON value.

jobs

The jobs field describes the individual jobs that make up this experiment. Each job contained within will be scheduled onto its own host and all scheduled jobs wihtin an experiment will be scheduled at the same time.

The key used in the object here will be the name of the job.

jobs.*.host.tags

A set of tags constraining which hosts this job can run on.

In order for this job to run on a host, that host must have tags which are a superset of those specified within the job.

jobs.*.steps

An array containing the individual steps that make up the job. These will be executed by the systemslab agent in the order they are specified in. Each step will wait for the previous one to complete before it is started unless background is set to true.

To see the documentation of what steps are available, see the step reference.

jobs.*.steps[*].uses

The name of the step to use.

The agent will look for a corresponding step binary under /usr/lib/systemslab-actions. Some step binaries are provided by SystemsLab but custom ones may also be added. See the [step reference][step ref] for documentation on which steps are available.

jobs.*.steps[*].with

The parameters for the step. This will always be a javascript object but which parameters are provided and what they do depends on the step binary.

jobs.*.steps[*].background

Whether this step should be started in the background. If true, then the agent will launch this step and immediately start the next one in the list. The agent will not wait for background steps to complete once it has completed all other steps, they will instead be killed as the job exits.

::: note Setting all jobs to have background: true, while not an error, is almost always the wrong thing to do. If this happens, the agent will immediately launch all the steps in the job and then also immediately kill them.

If you want to wait for a background step to complete it is necessary to do so yourself (e.g. by waiting for a PID to exit). :::

jobs.*.metadata

Metadata for an individual job. Like the top-level metadata field, this is a place to put arbitrary user-provided metadata for a job.

This must always be a JSON object, values within that object can be any JSON value.