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 switches | Data is displayed on the terminal as formatted text |
-P | Data is displayed on the terminal in Plot Format |
-f file | Raw 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 -P | Data 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 file | Data 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 -P | Data 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 file2 | This 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 -P | Data 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. |
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
To get a better idea of what the output actually looks like, see the examples.
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.
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.
sub mjs {
printf("%6d %6d %6d\\n",
$sysP[$NumCpus], $dskReadKBTot/$intSecs, $dskWriteKBTot/$intSecs);
}
1;
collectl --custom mjs:cd