Operational Modes and Formats

Operational Modes

Depending on which combination of switches are selected, collectl will run in one of 3 main modes with various options for added flexibility. The most basic mode, which you get if you don't select one of the other 2, is display. In this mode the output is displayed on the terminal in real-time as it is collected. In record mode, specified by the -f switch, data is written in real-time to a directory of the user's choosing with an optional prefix. In playback mode, selected with -p, data is read from a file that was generated in record mode at an earlier time.

The format of the results can also be selected as either Terminal or Plot. Terminal data is always displayed on the terminal while Plot data, selected by including -P with any of the 3 modes, can be either written to a file or displayed on the terminal. Since plot data is not intended for human consumption, the reason one would typically send it to a terminal would be with the intent of redirecting the output to a file or piping it into another script.

Using the -f, -p and -P switches in different combinations result in the following behaviors:

No switchesData is displayed on the terminal as formatted text
-PData is displayed on the terminal in Plot Format
-f fileRaw data is written to the file (whose name is constructed by collectl) in the same format as it occurred in /proc, with the extension raw. For more details on file naming see file naming.
-f file -PData is written to the specified file in plot format, with one or more of a number of extensions depending on what detail data may have been requested.
-p fileData is played back from the raw file specified by -p and displayed on the terminal as formatted text. If one wishes to view a subset of the data recorded, -s can be included to provide that discrimination. Note that if one specifies subsystems for which data has not been recorded, they will be displayed as zeros. One can also change the format that the data is display though various switches such as --verbose and -o.
-p file -PData is played back from the raw file and displayed on the terminal in Plot Format. Note that since one often uses this mode to produce output usable by other tools/programs, the user can force the output format by including -s and only those subsystems specified will be displayed. Furthermore, subsystems for which data has not been collected will also be displayed as zeros to ensure consistent formatting across multiple data files.
-p file1 -f file2This is NOT supported as you can only write data that is played back to another file in plot format. Someone wanting to do this should rethink what it is they are trying to do.
-p file1 -f file2 -PData is played back from the raw file and written to the specified file in Plot Format. Note that here too -s will force specific subsystems to be displayed.

Output Formats

By design, collectl gathers more data than is possible to display in an efficient, easy to read, compact form. However, most user want their data displayed in such a form for easy interpretation. Therefore, collectl will attempt to display all data in a single line, often choosing a subset of the complete data for each subsystem. If the user has selected too many systems, each line may exceed the display width and wrap. When this happens either make the terminal window wider (maybe even using a smaller font) or choose less subsystems. This is referred to as brief format and is collectl's display format of choice and therefore the default. Verbose mode displays more information and results in multiple lines of output.

Collectl will try its best to select a format consistent with the user's selection criteria, using brief mode whenever possible unless explicitly told no to do so. However there are several instances when this mode doesn't make sense. For example, detail data will always be displayed in verbose mode since it takes multiple lines for each sample. When this occurs, collectl will automatically use verbose which can also be manually forced for non-detail data using --verbose.

One should note that these formats are not just for interactive use and can also applied to playback mode as well.

An additional feature of brief output is subtotal mode. If one enters a at any time, the next line of ouput will be the subtotals (or averages on non-counters) of all columns since the start of collectl OR the last time the counters were zeroed. To zero the counters enter Z followed by a carriage return. Furthermore, if you type A followed by a carriage return, the averages will be reported. The averages/totals can also be displayed during playback in brief mode by specifying -oA.

To get a better idea of what the output actually looks like, see the examples.

Roll Your Own!

If you want to write your own display format - for perl programmers only - use --custom name:subsys in which you specify the name of the file to be required by perl, noting that the extension ph is assumed if not specified, and a list of subsystems that contain the desired data. You should also note that the entry point for the routine must match the name of the file. This feature hasn't been used by anyone but me (to my knowledge) and so hasn't had much exercise.

To actually write this routine one needs to know a little bit about how collectl works, but only a little. Based on the subsystems specified, data is read from /proc, so be sure to specify the correct subsystems from which you want to report data. At the beginning of the next cycle, the values are calculated and assigned to a whole slew of global variables. At this point the print routines are called and if --custom was specified the appropriate formatting routine is called instead of collectl's internal one and so when you use this capability you will not get any other output! To determine what to do in a custom display, you need only read through the print commands in the formatit.ph file and select the variables of your choice, often just cutting/pasting/editing various print statements. To get a rate/sec instead of an absolute count, be sure to divide by $intSecs, noting that you can still force an absolute value via -n since that always forces $intSecs to 1.

Here is an example of a very simply custom formatting routine that simply reports the system cpu time and the disk read/writes in KB.

sub mjs {
    printf("%6d  %6d  %6d\\n",
    $sysP[$NumCpus], $dskReadKBTot/$intSecs, $dskWriteKBTot/$intSecs);
}
1;
To run this routine once a second, simply execute the command:
collectl --custom mjs:cd