z/OSMF REST
The z/OS Management Facility exposes JES, the catalog, the z/OS UNIX file system, and the operator console as REST services over HTTPS. These scripts need no k6 extension, so any k6 binary can run them.
Scripts
| Script | Executor | Measures |
|---|---|---|
info.js |
1 iteration | Host reachable, credentials valid, TLS negotiated |
job-submit.js |
constant-arrival-rate |
JES turnaround: submit, poll, read spool, purge |
job-query.js |
ramping-vus |
Reading the output queue and spool. Read-only |
datasets.js |
constant-vus |
Catalog search, member listing, member read |
uss.js |
constant-vus |
Directory listing and file read |
console.js |
constant-vus |
MVS operator display commands |
mixed-workload.js |
three scenarios | All three profiles concurrently |
auth-secrets.js |
3 iterations | Authentication using a k6 secret source |
All of them import scripts/lib/zosmf.js, a client over the endpoints below.
Endpoints
| Operation | Method and path |
|---|---|
| Server information | GET /zosmf/info |
| Submit a job | PUT /zosmf/restjobs/jobs |
| List jobs | GET /zosmf/restjobs/jobs?owner=&prefix=&max-jobs= |
| Job status | GET /zosmf/restjobs/jobs/{jobname}/{jobid} |
| List spool files | GET /zosmf/restjobs/jobs/{jobname}/{jobid}/files |
| Read a spool file | GET /zosmf/restjobs/jobs/{jobname}/{jobid}/files/{id}/records |
| Purge a job | DELETE /zosmf/restjobs/jobs/{jobname}/{jobid} |
| Search the catalog | GET /zosmf/restfiles/ds?dslevel={pattern} |
| List PDS members | GET /zosmf/restfiles/ds/{dsname}/member |
| Read a data set | GET /zosmf/restfiles/ds/{dsname} |
| List a directory | GET /zosmf/restfiles/fs?path={path} |
| Read a USS file | GET /zosmf/restfiles/fs{path} |
| Issue a console command | PUT /zosmf/restconsoles/consoles/{name} |
Required request headers
z/OSMF rejects any request without X-CSRF-ZOSMF-HEADER. The value is ignored;
only the header’s presence is checked. scripts/lib/zosmf.js adds it to every
request:
const CSRF = { 'X-CSRF-ZOSMF-HEADER': '' };
Credentials go in an Authorization header rather than in the URL. k6 tags every
request with its URL, so https://user:pass@host would put the password into the
metric stream and into any exported summary.
const AUTHORIZATION = `Basic ${encoding.b64encode(`${zosmf.user}:${zosmf.password}`)}`;
The mock server enforces both rules, so a script that omits either fails locally.
Control metric cardinality with the name tag
k6 tags each request with its URL. Data set names and job ids vary per iteration,
so tagging on the raw URL creates one time series per resource. Pass a stable
name tag instead:
request('GET', `/zosmf/restfiles/ds/${dsname}`, null, { name: 'read data set' });
Thresholds can then target a single operation without naming a resource:
thresholds: {
'zosmf_request_duration{name:list data sets}': ['p(95) < 10000'],
'zosmf_request_duration{name:read data set}': ['p(95) < 3000'],
}
Metrics
scripts/lib/zosmf.js defines these in addition to k6’s built-in HTTP metrics.
| Metric | Type | Description |
|---|---|---|
zosmf_request_duration |
Trend (ms) | Per-request duration, tagged with name |
zosmf_success |
Rate | Proportion of requests returning 2xx |
zosmf_errors |
Counter | Non-2xx responses, tagged with name and status |
zos_job_turnaround |
Trend (ms) | Submit to OUTPUT, recorded by waitForJob() |
Submit a job and wait for it
To submit JCL inline, set the internal reader attributes on the request. Fixed 80-byte records in text mode is what JES expects from a card reader:
export function submitJcl(jcl) {
return request('PUT', '/zosmf/restjobs/jobs', jcl, {
headers: {
'Content-Type': 'text/plain; charset=utf8',
'X-IBM-Intrdr-Recfm': 'F',
'X-IBM-Intrdr-Lrecl': '80',
'X-IBM-Intrdr-Mode': 'TEXT',
},
});
}
| Header | Value | Purpose |
|---|---|---|
Content-Type |
text/plain; charset=utf8 |
Body encoding. Without the charset, z/OSMF applies its own default |
X-IBM-Intrdr-Recfm |
F |
Fixed-length records |
X-IBM-Intrdr-Lrecl |
80 |
80-byte records |
X-IBM-Intrdr-Mode |
TEXT |
Text rather than binary |
z/OSMF also accepts X-IBM-Intrdr-Class to set the internal reader class. The
scripts do not send it, because job class is already on the JOB card that
scripts/lib/jcl.js builds from ZOS_JOB_CLASS. Sending both invites the two
values to disagree.
This header set matches the one Zowe CLI sends in submitJclCommon.
A successful submit returns 201 and a job document containing jobname and
jobid. waitForJob() polls GET /zosmf/restjobs/jobs/{jobname}/{jobid} until
status becomes OUTPUT, then records zos_job_turnaround.
Run the script:
k6 run \
-e ZOSMF_URL=https://zosmf.example.com \
-e ZOS_USER=IBMUSER -e ZOS_PASSWORD="$ZOS_PASSWORD" \
-e ZOS_ACCOUNT='ACCT#' \
-e ZOS_JOBS_PER_MINUTE=12 \
scripts/zosmf/job-submit.js
The script uses constant-arrival-rate rather than a VU count, because JES queue
depth is a function of submission rate.
The default job is IEFBR14, which allocates nothing and returns zero, so the
measurement covers submission, scheduling, and spool handling rather than any
application. Set ZOS_JOB_WITH_OUTPUT=true to submit an IEBGENER job that
produces real spool output.
To submit JCL that already exists on the host, use the JSON form:
submitDataset("IBMUSER.JCL(COMPILE)");
// PUT /zosmf/restjobs/jobs {"file": "//'IBMUSER.JCL(COMPILE)'"}
The script purges every job it submits. A run at 12 jobs a minute for an hour leaves 720 held output data sets if the purge is removed. If you change that step, arrange for something else to clean up.
Issue operator commands
console.js sends display commands and asserts on the message id in the
response:
const COMMANDS = [
{ cmd: 'D IPLINFO', expect: 'IEE254I' },
{ cmd: 'D T', expect: 'IEE136I' },
{ cmd: 'D M=CPU', expect: 'IEE174I' },
{ cmd: 'D GRS,C', expect: 'ISG343I' },
];
The response body contains cmd-response for commands that answer immediately.
Commands whose messages arrive later return cmd-response-key, which the script
passes to GET /zosmf/restconsoles/consoles/{name}/solmsgs/{key}.
The console service runs any command you send with the authority of the authenticated user. The list above contains display commands only.
setup() issues D T first and fails with a clear message if the user lacks
CONSOLE authority in RACF.
Concurrency defaults to 2 VUs because the console serialises commands. Higher values measure the console’s queue rather than the system’s response.
Enable writes explicitly
datasets.js and uss.js are read-only unless you set both variables:
k6 run -e ZOS_ALLOW_WRITE=true -e ZOS_WRITE_TARGET='IBMUSER.K6.TEST' \
scripts/zosmf/datasets.js
Without ZOS_WRITE_TARGET, the script throws rather than guessing a data set
name.
Run several load profiles at once
mixed-workload.js runs three scenarios concurrently, each with its own executor
and its own workload tag:
scenarios: {
batch: { executor: 'constant-arrival-rate', exec: 'batchSubmission', rate: 4, timeUnit: '1m' },
catalog: { executor: 'ramping-vus', exec: 'catalogSearch' },
operator: { executor: 'constant-vus', exec: 'operatorCommand', vus: 1, startTime: '1m' },
}
Because each scenario tags its requests, thresholds can hold each to a separate budget:
thresholds: {
'zosmf_request_duration{workload:batch}': ['p(95) < 5000'],
'zosmf_request_duration{workload:catalog}': ['p(95) < 15000'],
}
The script also defines handleSummary() to print the four numbers a capacity
review needs and write the full report to summary.json.
Run without a mainframe
tools/mock-zosmf.py implements the endpoints above using only the Python
standard library. Its job queue moves a submission from INPUT through ACTIVE
to OUTPUT over about two seconds, and it seeds three jobs at startup so the
read-only scripts have something to browse.
python3 tools/mock-zosmf.py --port 10443 --verbose
To run the whole z/OSMF set against it:
make test
The mock is not an emulator. Its response times say nothing about a real z/OSMF. Use it to verify that a script behaves as expected before it reaches a real system.
Troubleshooting
| Symptom | Cause |
|---|---|
| 401 on every request | ZOS_PASSWORD unset or wrong, or the user is revoked in RACF |
400 with missing X-CSRF-ZOSMF-HEADER |
Request built without scripts/lib/zosmf.js |
| TLS handshake failure | z/OSMF certificate not in the load generator’s trust store. Confirm with ZOS_TLS_INSECURE=true, then fix the trust store |
| 403 from the console service | User lacks CONSOLE authority in RACF |
job-query.js throws in setup() |
No jobs match ZOS_JOB_OWNER and ZOS_JOB_PREFIX |
| Catalog search times out | ZOS_DSLEVEL is too broad. Narrow the qualifier |