- Difficulty level: easy
- Time need to lean: 10 minutes or less
- Key points:
-vcontrols logging level fromerror,warning,infotodebug-v1displays all workflow output,-v2displays workflow output plus workflow information,-v3displays some debug information.-v0suppress all user output (except for errors) and introduces a special text-based progress bar- Environment variable
DBG_DEBUGcan be used to generate topic-specific debug information -jcontrols number of concurrent processes
SoS uses a logging system to output all sorts of information during the execution of workflows. The amount of output can be controlled by logging level, which can be error (0), warning (1), info (2), and debug (3). The default logging level for SoS is info.
For example, logging at info level would produce message indicating the steps executed and input output files, while -v0 will suppress all but error messages. It is worth noting that if you are using SoS Notebook, all logging messages will be sent to the side panel if the console panel is open.
Text-based progress bar with -v0
If you have a large workflow with lots of steps, the default output can be overwhelming. In this case you can use -v0, which not only suppress all `INFO` messages and script output, but also introduces a text-based progress bar from which you can learn the progress of the workflow easily.
In -v1 mode, all output from user statements will be outputted
SoS will output additional logging information at level -v2
Logging messages are by default sent to console panel in SoS Notebook
If you are executing the workflow in SoS notebook with the console panel open, all logging messages will be sent to the console panel. In particular, the output of your workflow in `-v2` mode in the notebook will be identical to `-v1`
This option is designed for developers but if you would like to peak into what SoS is actually doing, you can set an environment variable SOS_DEBUG, with , separated values of
ALL: all debug messages- Topics such as
CONTROLLER,TASK,WORKER,EXECUTORto keep only debug information of specific topics. The actual values can vary so you should check the output of commandsos run -hfor acceptable topics. - A filename with an extension, or
-for standard error output, or nothing to use~/sos_debug.logas default.
For example,
export SOS_DEBUG=ALL
will save a large amount of debug information to ~/sos_debug.log, regardless of verbosity level set by -v,
export SOS_DEBUG=TASK,-
will send task related debug information to the terminal, and
export SOS_DEBUG=ALL,myrun.log
will save all debug information in myrun.log, which can be useful if you notice something wrong with SoS or your workflow and would like to submit a bug report.
Control number of workers with option -j
Option -j sets the number of workers for SoS. The default value is half of the number of processes.
SoS dispatch steps, substeps, and nested workflows to dedicated workers. The maximum number of concurrent workers can be controlled by the -j option. Although the default value, which is half of the number of processes of the computer, is good most of the time, you might want to control the number of workers depending on your running environment (e.g. on a shared server) or on the size of your workflow. Note that -j specifies the number of workers so the total number of processes started by sos can be at most n + 1 with option -j n.
Dedicated workers for blocking nested workflows
Ocassionally you might see more than n + 1 SoS processes when you execute a workflow with option `-j n`. This is because the workflow consists of blocking nested workflows, namely nested workflows not as the last statement of a step. For example, the nested workflow `A` in the following SoS step has to be executed in a blocking fashion before `some_other_computation` can be done,
[10]
sos_run('A')
some_other_computation()
So SoS spawns a separate process for nested workflow A so that it will not affect the concurrent execution of other parts of the workflow.
A more advanced version of option -j allows the specification of multiple workers on multiple remote workers. For example, if you have host1 and host2 directly accessible by the localhost (through public-key authentication) and with SoS installed, you can create workers on these hosts through
sos run script workflow -j 4 host1:4 host2:4
which will start 4 workers locally, 4 workers on host1 and 4 workers on host2.
In practice, however, this option is rarely used directly and is specified on cluster systems when multiple nodes are allocated to execute a workflow.