k6-z Grafana k6 on IBM z/OS

ZOAU

IBM Z Open Automation Utilities exposes data sets, jobs, and the operator console as z/OS UNIX commands. Any transport that can run a shell command can drive them, so k6 reaches them either over SSH with xk6-ssh or by forking locally with xk6-exec.

ZOAU is a licensed IBM product. Without it, use z/OSMF instead.

Scripts

Script Transport Executor Measures
ssh/zoau-datasets.js SSH constant-vus, 1 VU Catalog listing, member listing, member read
ssh/zoau-job.js SSH constant-vus, 1 VU jsub, poll jls, read jcat
ssh/zoau-opercmd.js SSH constant-vus, 1 VU Operator display commands
exec/zoau-local.js Local fork ramping-vus The same operations, k6 running on z/OS

Commands used

Command Description
dls List data sets. -l adds organisation, -u adds space
dcat Read a sequential data set or a PDS member
jsub Submit JCL from a data set or a file
jls Query the job queue
jcat Read a job’s output
jdel Purge a job
opercmd Issue an MVS operator command
mvscmd Run a program with DD allocations, without JCL

The samples issue these operator commands, all of which are display commands from IBM’s zoau-samples:

opercmd 'd iplinfo'
opercmd 'd m=cpu'
opercmd 'd grs,c'
opercmd 'd omvs,limits'

opercmd runs any command you give it with the authority of the signed-on user. Treat the command list in scripts/lib/zoau.js the way you would treat a production runbook.

Choose a transport

Situation Transport
Load generator off-platform, low request volume SSH
You need concurrency z/OSMF, or exec on the host
Measuring ZOAU without network latency in the result exec on the host
No ZOAU licence z/OSMF only

The SSH scripts run at vus: 1 and you should not raise it. xk6-ssh registers a single module object shared by every VU, so a second VU calling connect() replaces the first VU's session mid-iteration.

The cause is how the extension registers with k6. An extension implementing k6’s Module interface gets a fresh instance per VU; one that registers a plain value does not, and xk6-ssh registers a plain value. To generate concurrency over SSH, run several k6 processes.

Set the ZOAU environment explicitly

A non-interactive SSH session does not run the login profile, so ZOAU is not on PATH and its Python libraries are not on LIBPATH. scripts/lib/zoau.js prefixes every command rather than relying on the remote user’s shell setup:

export function withEnvironment(command) {
  return [
    `export ZOAU_HOME=${zoau.home}`,
    `export PATH=${zoau.home}/bin:$PATH`,
    `export LIBPATH=${zoau.home}/lib:$LIBPATH`,
    `export PYTHONPATH=${zoau.pythonPath}:$PYTHONPATH`,
    command,
  ].join('; ');
}

Set ZOAU_HOME if your installation is not at /usr/lpp/IBM/zoau.

Recover the exit code

ssh.run() returns stdout only. There is no exit status, and ZOAU writes diagnostics to stderr, so a failing command returns an empty string with no indication of why.

instrumented() redirects stderr into stdout and appends the return code:

export function instrumented(command) {
  return withEnvironment(`{ ${command} ; } 2>&1 ; echo "__RC=$?"`);
}

parseResult() splits the return code off the last line, returns the remaining output, and increments zoau_command_failures when the code is non-zero.

Submit a job

The script writes JCL to a temporary z/OS UNIX file, submits it with jsub, polls jls until the job leaves the queue, reads the output with jcat, then purges the job and removes the file.

k6 run \
  -e ZOS_SSH_HOST=zos.example.com \
  -e ZOS_USER=IBMUSER -e ZOS_PASSWORD="$ZOS_PASSWORD" \
  -e ZOS_ACCOUNT='ACCT#' \
  scripts/ssh/zoau-job.js

The heredoc is quoted so the shell does not expand anything inside the JCL:

run(`cat > ${path} <<'ENDJCL'\n${jcl}\nENDJCL`, 'stage jcl');

jls reports a completed job with status CC and the return code in the next column. ABEND and JCLERR are the two terminal failure states:

if (job && ['CC', 'ABEND', 'JCLERR'].includes(job.status)) {
  break;
}

This measures the same thing as scripts/zosmf/job-submit.js over a different transport. Running both separates JES turnaround from z/OSMF’s own overhead.

Run on the host with no SSH hop

exec/zoau-local.js uses k6/x/exec, which forks a process per call. xk6-exec implements k6’s Module interface, so it creates an instance per VU and scales with VU count.

k6 run -e ZOS_VUS=4 scripts/exec/zoau-local.js

This needs a k6 built for z/OS that includes xk6-exec. The zopen package is vanilla k6 and does not include it; see install. The same script runs unchanged on Linux on Z or in zCX against a local ZOAU.

There is no shell wrapping the call, so the environment is passed as an argument:

exec.command('sh', ['-c', command], {
  env: [`ZOAU_HOME=${zoau.home}`, `PATH=${zoau.home}/bin:/bin:/usr/bin`],
  combine_output: true,
  continue_on_error: true,
});

combine_output folds stderr into the result for the same reason as the SSH redirect. Without it, a failing command returns an empty string.

Metrics

Metric Type Description
zoau_command_duration Trend (ms) Per-command duration, tagged with command
zoau_command_failures Counter Commands returning a non-zero code
zoau_job_turnaround Trend (ms) Submit to completion, zoau-job.js only
zoau_catalog_entries Trend Data sets returned by dls, zoau-local.js only

Troubleshooting

Symptom Cause
dls: command not found ZOAU_HOME is wrong, or ZOAU is not installed
Every command returns rc 0 with empty output LIBPATH is not set, so the ZOAU binaries cannot load their libraries
SSH results interleave between VUs VU count above 1. The SSH scripts are single-VU by design
setup() fails immediately Neither ZOS_PASSWORD nor ZOS_SSH_KEY is set
opercmd returns an authority error The user lacks console authority in RACF