Job Environment Reference

The SystemsLab runner sets the environment variables on this page whenever it starts a step. Built-in steps like shell pass them on to the programs they run, so your scripts can read them directly. Custom action binaries see them too.

The variables exist only while the job runs. They are not available during jsonnet evaluation, so substitute them at run time, for example with sed or envsubst.

- uses: shell
  with:
    run: |
      echo "job $SYSTEMSLAB_JOB_NAME replica $SYSTEMSLAB_JOB_INDEX"
      echo "redis is at $REDIS_ADDR"

The runner does not clear its own environment first, so a step also inherits whatever environment the SystemsLab agent was started with (PATH, HOME, and so on).

General

SYSTEMSLAB

Always 1. Check it to tell whether a script is running inside a SystemsLab job.

CI

Always 1. Many tools use it to switch off interactive prompts and progress bars.

Job identity

SYSTEMSLAB_EXPERIMENT_ID

The UUID of the experiment this job belongs to.

SYSTEMSLAB_JOB_ID

The UUID of this job. Each replica of a replicated job has its own job ID.

SYSTEMSLAB_JOB_NAME

The job's name, as given by its key in the experiment's jobs object. Every replica of a replicated job has the same name.

SYSTEMSLAB_JOB_INDEX

The replica index of this job, starting at 0. A job with replicate: N runs as N jobs with indices 0 to N - 1. A job without replicate always has index 0.

local systemslab = import 'systemslab.libsonnet';

{
  jobs: {
    client: {
      replicate: 3,
      steps: [
        // Prints 0, 1 or 2 depending on the replica.
        systemslab.bash('echo "$SYSTEMSLAB_JOB_INDEX"'),
      ],
    },
  },
}

SYSTEMSLAB_RUN_ID

The attempt number for this job, starting at 0. If SystemsLab has to rerun an experiment, for example because the host it was running on disappeared, the new attempt gets a higher run ID.

SYSTEMSLAB_HOST_ID

The UUID of the agent (host) that is running this job.

Addresses of other jobs

For every job in the experiment that has been assigned a host, including this job itself, the runner sets variables holding that host's IP address. The variable name starts with the job name in upper case, with . and - replaced by _:

Variable	Value
<NAME><INDEX>_ADDR	The address of replica <INDEX> of the job.
<NAME>_ADDR	The address of replica 0 of the job.

For example, an experiment with a redis job and a load-gen job with replicate: 2 gets:

REDIS_ADDR=10.0.0.1
REDIS0_ADDR=10.0.0.1
LOAD_GEN_ADDR=10.0.0.2
LOAD_GEN0_ADDR=10.0.0.2
LOAD_GEN1_ADDR=10.0.0.3

The value is a bare IP address with no port.

WARNING

SystemsLab does not check that these variable names are unique. Job names that differ only in case or in . versus - (such as foo-bar and foo.bar) map to the same variable, and so can a name ending in a digit (replica 0 of node1 and replica 10 of node are both NODE10_ADDR). When two jobs share a variable only one address is kept, so choose job names that stay distinct after the conversion.

TIP

If the systemslab-nss package is installed on the host, the same addresses also resolve through DNS as <index>.<name>.systemslab.internal, and replica 0 also as <name>.systemslab.internal.

Runner internals

Built-in steps use these variables to talk to the runner and the server. Custom actions may use them too, but most scripts will not need them.

SYSTEMSLAB_SERVER_URL

The URL at which the runner reaches the SystemsLab server.

SYSTEMSLAB_RUNNER_SOCKET

The path to the unix socket the runner listens on for this job. The start-metrics and stop-metrics steps use it to ask the runner to start and stop metrics recording.

SYSTEMSLAB_CGROUP

The path of the cgroup the agent started the runner in. It is set only when the agent is configured to run jobs in cgroups.