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:

  1. a date and time specified in string with format YYYY-mm-dd HH:MM, only value in the future are accepted.
  2. the string now, that means if the job can't scheduled immediately it is rejected
  3. 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 is YYY-mm-dd HH:MM while the short is HH: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 platform
  • bin_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 of jobFile.json so it is relative to it
  • targets: 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 them
  • programAddress (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 called test.log file is used, it contains all logs (also the serial log of each node)
  • 1: as 0 plus a serial.log file is used that contains only serial logs messages from nodes
  • 2: as 1 plus for each nose a serial.{nodeId}.log file is used to gather each node serial log messaged
  • 3: 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 string python can be used
  • file: 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 of jobFile.json and is relative
  • init (optional): specify which function in the python file should be used to initialize the job
  • init_args (optional): see note
  • init_kargs (optional): see note
  • run (optional): specify which function in python file should use to run the job
  • run_args (optional): see note
  • run_kargs (optional): see note

Note:

  1. if neither init or run are specified orchestrator result not used
  2. 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:
    1. the run function return
    2. the duration time expires
  3. init and run function signatures should be one of the following:
    1. funcname(job): take only an argument
    2. 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 from init_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.