colplot - plots collectl data using gnuplot
colplot -plot plots [-switches]
Generate the plots selected by PLOT(s) on either the terminal, a file or
delivered as email. The switches control the files to plot, the timeframes,
formats and destinations. In the case of a web based display, you can run in
`live` mode which will provide for periodic screen refreshes for viewing
real-time data. See the web-based help and FAQ for more detail.
The plots themselves are selected from the standard list (see -showplots) with
List one or more plot names either separated
with commas and no whitespace or if you want to include whitespace be sure to
enclose the string in quotes.
The remainder of the switches which are all optional fall into several
categories, the first being those that select the files and timeframes to plot
and are as follow:
Look in this directory for plot files rather
than the one pointed to by PlotDir in colplot.conf. A plot file is one with a
known extension and a properly formatted name. Any files that fail either of
these tests will be ignored.
-contains string1 [string2...]
This field consists of one or more strings
separated by commas or whitespace (if whitespace the entire string must be
quoted). Each selected plot file has its name compared to each string. Unless
-any is specified, each string must appear somewhere in that file name for it
to continue to be selected.
As a special case, if there is a string containing a [, it is assumed to be in
pdsh format, a compact format for specifying multiple hostnames, eg
xyz[1-5,10] specifies 6 hosts whose names all begin with xyz and are followed
by one of 6 values. In this case, only files with hostnames exactly matching
these names will be selected.
If specified all strings specified by
-contains must match for a file to be seleceted for plotting.
The starting and ending date between which
files are selected for plotting. The dates must be in yyyymmdd format.
Once all the files matching the selection
criteria are discovered, use the more recent file access time to determine the
ending time for plotting data. Note, if you've copied the file from elsewhere
and didn't preserve the last access time in the newly created files this will
produce unexpected results.
The starting and ending time between which
data is plotted. The times must be in hh:mm OR hh:mm:ss format. The hour
portion may be 1 or 2 digits.
The next set of switches control which plots are actually displayed
-filters string1 [string2...]
These only apply to detail plots. They select
which devices to produce plots for. Invalid or unknown devics are ignored. In
other words, if one selects "-filters eth xyz d1" and requests
network plots, only ethernet devices will be displayed. Since 'xyz' is an
invalid selection string it is ignored. Since there are no network devices
with 'd1' in their names, it too will be ignored. If one choses network and
disk plots, ethernet devices as well as any disk names with a 'd1' in them
will be displayed.
By default, plots are geneated using solid
lines. However, one can request a different format be used including points or
stacked line or stacked points.
If one generates multiple unique plot files
per day via the -ou switch in collectl, those files will be ignored by
colplot. This switch, currently only available via the CLI will cause those
files to be selected and displayed in the same plot.
The next set of switches deal with plot formatting, typically only used under
unusual circumstances since the default formats meet most needs:
Colplot uses a default height for the vertical
axis which can be overridden via -height. However sometimes a plot is not high
enough for all the labels to fit in the legend. This switch will keep the user
specified height for all plots in which the legend fits as a single column but
increase the heights of those that aren't high enough.
This switch must be used in conjunction with
selecting a destination other than the terminal, specifically email or
directory. One can use it to change the default from a PDF file to either a
PNG file for each plot or TTY to send PNG output for one plot to STDOUT.
This controls the vertical hight of a plot.
This width also includes the xaxis and you can therefore increase the room
taken by a single plot by choosing -noxaxis.
This removes the legend from the plotting
area, causing the plot to become physically wider.
This removed the xaxis from the plotting area,
causing the plot to become physically taller.
For some people the thickness of the lines in
a plot may be too thin to clearly see the different color variations of the
lines. Versions of gnuplot >= 4.2 support wider lines and therefore so does
colplot. If using scatter plots, a different plotting symbol is actually used.
Values of 2 or 3 are usually sufficient.
This switch controls the width of a plot where
1 is the size of a printable page. If set to more than 1 and either -file or
-mail is chosen it will be forced to 1. By setting this number to less than 1,
it may be possible to fit more than one plot on a page or screen. As this
width also includes the legend, you can further reduce the plot size by
This causes a tic mark to be drawn on the
xaxis every n seconds. It usually doesn't make sense unless you've chosen a
fairly narrow timeframe in which to generate a plot.
Make the y-axis logrithmic.
This set of switches deal with the plot destination when it is NOT the terminal
Linux only. Address to send plot file(s) to.
The only syntax check is for an '@' to appear somewhere in the address
The name of directory into which the plot
file(s) will be placed. The directory must exist.
Print the hrefs that would be used if run from
Really only intended for users familiar with
gnuplot, this is the control file used to generate the plots. It allows
someone to manually edit the file to change the plot appearance and/or labels
by rerunning gnuplot using its settings.
Instead of generating a page break in a pdf
file whenever a page fills, this flag will cause a page break whenever the
Use this subject in email rather than the
And finally for completeness there are several types of help:
This is really a debugging aid, intended for
developers and/or people building custom plot definitions. When specified, the
plotting parameters for each selected plot will be shown. Of particular value
is the actual column number for each data element in each selected file.
List the names of all the standard plots
available for use with the -plots switch.
Show both the versions of both colplot as well
This program was written by Mark Seger (firstname.lastname@example.org).
Copyright 2003-2015 Hewlett-Packard Development Company, L.P.