Job file specifications
Introduction
The purpose of this documents is explain how to write a jobFile.json
file to
configure and run an experiment on testbed.
As the extension of the filename show the experiment is defined by JSON file and its field can be grouped in four category: mandatory, optional, not used, deprecated.
This document is organized in other four section, one for each category, that will explain all of them.
Mandatory fields
Mandatory field is need and if one of them is not defined or not valid the job is rejected. Hereafter the mandatory field with their explanation.
test_id
type: int
default value:
This field is assigned by the server when the file is validated, it represent a unique ID of the job. If the field is not present in the JSON it will be added, if is presented its value is ignored and overwrote.
start_time
type: string
default value:
This field specify when a job should scheduled, valid value are:
- a date and time specified in string with format
YYYY-mm-dd HH:MM
, only value in the future are accepted. - the string
now
, that means if the job can't scheduled immediately it is rejected - the string
asap [reference]
, that means the job is scheduled as soon the testbed is free for an amount of time that permit to execute that job.reference
is a optional parameter, if indicated the job is schdueld after that moment. reference can have two forms: the full and short. The full form isYYY-mm-dd HH:MM
while the short isHH:MM
that implies today. If the refernce time is in the past it is ignored
Note: testbed scheduling is done with minute precision that means a job always start a second 00 of a minute. For this reason date and time values are without seconds and now means scheduled within a minute.
duration
type: int
default value:
This field define the duration of the job, it is expressed in second. The duration of test start after the job is initialized (node are programmed and a first check of node that started is done). Only positive number are accepted.
Note a job require 40 s more its duration, 40 s is the time the testbed need to initialize and shutdown a job.
binaries
type: complex
default value:
It specify which software should work on the nodes, it can be a single complex value or a list of complex values in case different program have to be used.
This is a complex field contains the following sub fields:
hardware
: this is a string that contain the name of the platformbin_file
: this is the path of the binary file, at user side can be the absolute or relative, at server side all file of a job are in same directory ofjobFile.json
so it is relative to ittargets
: it is a list of element, each element is a single node id (int) or a name (string) of a node group, see testbed information for themprogramAddress
(optional): if it is specified it is used by the program that flash the node memory to upload correctly the binary file.
Optional field
Optional field if present affect how a job is run or behave, an optional field with invalid value cause the rejection of the job. Some of them are in lazy field, they have a default value that is used if not specified, the user can change it setting it explicitly.
logs
type: int
default value: 0
This field specify the verbosity of file:
0
: only a log file calledtest.log
file is used, it contains all logs (also the serial log of each node)1
: as 0 plus aserial.log
file is used that contains only serial logs messages from nodes2
: as 1 plus for each nose aserial.{nodeId}.log
file is used to gather each node serial log messaged3
: as 1 plus for each node and each platform a{hardware}.{nodeId}.log
file is used to gather only serial node for the specified platform on specified node.
snapshot
type: false
, string or list of string
default value: false
This fields set if when job is run a snapshot of node configuration is added or not to
the job archive.
If the value is false
(default) any snapshot is added.
Otherwise the value can be csv
or python
in which case the snapshot in that format is
added. A list of string (each one with permitted value) means all snapshot specified format
will be added.
The format of file are available at this link.
orchestrator
type: complex
default value:
If specified the testbed use this information too coordinate and interact with the nodes during the test.
:warning: At the moment only Python orchestrator can be used.
A single value can be specified with this sub fields:
type
: only stringpython
can be usedfile
: the file that contain the python code, at user side can be an ab- solute or relative path, at server side the file is saved in same folder ofjobFile.json
and is relativeinit
(optional): specify which function in the python file should be used to initialize the jobinit_args
(optional): see noteinit_kargs
(optional): see noterun
(optional): specify which function in python file should use to run the jobrun_args
(optional): see noterun_kargs
(optional): see note
Note:
- if neither
init
orrun
are specified orchestrator result not used - when
run
function is specified it controls the duration of the test and duration field is used to limit it, the test ends when the first of this two condition occurs:- the
run
function return - the
duration
time expires
- the
init
andrun
function signatures should be one of the following:- funcname(job): take only an argument
- funcname(job, param1[=default1], param2[=default2]): first argument as before followed by a list of
argument, the argument are passed as positional argument from
init_args
subfield or as named argument frominit_kargs
subfield
The only one or the first argument is the job it self for the init
function
and an activeTestbed object for the run function[^Need more documentation]
Deprecated field
Deprecated field are the field that was optional or mandatory in previous version of testbed software but now are renamed, modified or ignored.
To maintain compatibility with previous version, for a period, those field can be automatically corrected
and a warning message it is shown to permit the user to updated its jobFile.json
.
After that grace period expire the warningg is transformed in an error and the job will be rejected.
ts_init
This field is substituted by the start_time
field, to update just rename the
field.
image
This field is substituted by the binaries
field to update just rename it and
its/their subfields.
python script
This should be changed in a orchestrator
field, it also permit more flexibility
and pass the value to argument. The following
"python_script" : "pFile.py",
is equivalent and can be changed in
"orchestrator" : {
"type": "python",
"file": "pFile.py",
"run": "run_test"
}
Not used
All the field that are not listed on previous section are not used fields and are ignored by the testbed. Those filed can be useful for the user to tag or specify some information about the test.
An example can be the fields name and description that give an explanation of the purpose of the test. Another example can be add a git refs to know which version of a software is used.