resource_monitor(1)

NAME

resource_monitor - monitors the cpu, memory, io, and disk usage of a tree of processes.

SYNOPSIS

resource_monitor [options] -- command [command-options]

DESCRIPTION

resource_monitor is a tool to monitor the computational resources used by the process created by the command given as an argument, and all its descendants. The monitor works 'indirectly', that is, by observing how the environment changed while a process was running, therefore all the information reported should be considered just as an estimate (this is in contrast with direct methods, such as ptrace). It has been tested in Linux, FreeBSD, and Darwin, and can be used automatically by makeflow and work queue applications. Additionally, the user can specify maximum resource limits in the form of a file, or a string given at the command line. If one of the resources goes over the limit specified, then the monitor terminates the task, and reports which resource went over the respective limits. In systems that support it, resource_monitor wraps some libc functions to obtain a better estimate of the resources used. Currently, the monitor does not support interactive applications. That is, if a process issues a read call from standard input, and standard input has not been redirected, then the tree process is terminated. This is likely to change in future versions of the tool. resource_monitor generates up to three log files: a summary file encoded as json with the maximum values of resource used, a time-series that shows the resources used at given time intervals, and a list of files that were opened during execution. The summary file is a JSON document with the following fields. Unless indicated, all fields are integers.
command:                  the command line given as an argument
start:                    microseconds at start of execution, since the epoch
end:                      microseconds at end of execution, since the epoch
exit_type:                one of "normal", "signal" or "limit" (a string)
signal:                   number of the signal that terminated the process
                          Only present if exit_type is signal
cores:                    maximum number of cores used
cores_avg:                number of cores as cpu_time/wall_time (a float)
exit_status:              final status of the parent process
max_concurrent_processes: the maximum number of processes running concurrently
total_processes:          count of all of the processes created
wall_time:                microseconds spent during execution, end - start
cpu_time:                 user+system time of the execution, in microseconds
virtual_memory:           maximum virtual memory across all processes, in MB
memory:                   maximum resident size across all processes, in MB
swap_memory:              maximum swap usage across all processes, in MB
bytes_read:               amount of data read from disk, in MB
bytes_written:            amount of data written to disk, in MB
bytes_received:           amount of data read from network interfaces, in MB
bytes_sent:               amount of data written to network interfaces, in MB
bandwidth:                maximum bandwidth used, in Mbps
total_files:              total maximum number of files and directories of
                          all the working directories in the tree
disk:                     size in MB of all working directories in the tree
limits_exceeded:          resources over the limit with -l, -L options (JSON)
peak_times:               seconds from start when a maximum occured (JSON)
snapshots:                List of intermediate measurements, identified by
                          snapshot_name (JSON)
The time-series log has a row per time sample. For each row, the columns have the following meaning (all columns are integers):
wall_clock                the sample time, since the epoch, in microseconds
cpu_time                  accumulated user + kernel time, in microseconds
cores                     current number of cores used
max_concurrent_processes  concurrent processes at the time of the sample
virtual_memory            current virtual memory size, in MB
memory                    current resident memory size, in MB
swap_memory               current swap usage, in MB
bytes_read                accumulated number of bytes read, in bytes
bytes_written             accumulated number of bytes written, in bytes
bytes_received            accumulated number of bytes received, in bytes
bytes_sent                accumulated number of bytes sent, in bytes
bandwidth                 current bandwidth, in bps
total_files               current number of files and directories, across all
                          working directories in the tree
disk                      current size of working directories in the tree, in MB

OPTIONS

-d,--debug <subsystem>
Enable debugging for this subsystem.
-o,--debug-file <file>
Write debugging output to this file. By default, debugging is sent to stderr (":stderr"). You may specify logs be sent to stdout (":stdout"), to the system syslog (":syslog"), or to the systemd journal (":journal").
-i,--interval <n>
Interval between observations, in seconds (default=1).
-c,--sh <str>
Read command line from , and execute as '/bin/sh -c '.
-l,--limits-file <file>
Use maxfile with list of var: value pairs for resource limits.
-L,--limits <string>
String of the form "var: value, var: value\ to specify resource limits. (Could be specified multiple times.)
-f, --child-in-foreground Keep the monitored process in foreground (for interactive use).
-O,--with-output-files <template>
Specify template for log files (default=resource-pid-).
--with-time-series Write resource time series to