GENPLOTFILES(1) colplot GENPLOTFILES(1)NAME
genplotfiles - utility to help automate creation of collectl plot file from raw ones
SYNOPSIS
/opt/hp/colplot/genplotfiles.pl -outdir [-switches]
DESCRIPTIONS
This utility is not intended to meet all plot file creation needs, but quite frankly should meet most. Features not provided with this
utility are best realized by running collectl directly in playback mode (see collectl -p). It is therefore important to understand what
this utility will and will not do for you before building an automation strategy around it.
The algorithm used is fairly simple - genplotfiles examines each collectl raw file to see it it falls within the data ranges (if specified)
and contains a matching hostname (if specified). If a plot file already exists, the timestamps are compared and the raw file skipped if
its newer than the plotfile.
Any raw files that pass all these tests are then passed to collectl with their timestamp wildcarded. The result is all raw files for that
host/date will be processed. This means if you copy over collectl raw files multiple times over the course of the day using rsync, you can
immediately genererate up-to-date plots for them using genplotfiles. Furthermore, you won`t even need any date parameters if the older
plot files are alreay up to date.
For an example of what a cron job that aggregates multiple collectl logs onto a single system for plotting purposes, see crontab.sh in the
same directory as this script.
SWITCHES
All switches are optional with the exception of -outdir:
-colbin path-to-collectl
This points to collectl and is only necessary if /usr/sbin is not in your path or you`ve chosen to install collectl in a non-stan-
dard directory.
-debug number
Primarily for development, will provide intermediate processing information based on its value. See souce for details.
-force
Always generate plot files even in there is an existing one that is newer than the latest raw file. This will be necessary if you
want to rerun this script and just change the value of -subsys.
-help
Print a summary of available switches.
-host string
Only process files that contain this string in their hostname portion of the filename.
-indir directory
Directory where to look for collectl logs. The default is /var/log/collectl and is therefore only necessary if your logs are in a
non-standard location.
-outdir directory
Directory into which to write the plottable files. This field is required.
-fromdate date
Ignore files with a datestamp in their name less that this value. The default is 20050101 and so defaults to all files. The value
of `yesterday` is also recognized to simplify scripts that call this.
-thrudate date
Ignore files with a datestamp in their name with a datestamp greater than this value. The default is the current day and one can
also specify a value of `yesterday`.
-subsys string
Instead of using the default subsystems for which data was collected, generate output files based on this set. There are basically
two reasons for doing this. The first is that you may want to reduce the size of the plot files, though with compression there is
rarely much point in this. The second is if you`ve asked collectl to collect summary data but want to plot detail data.
See the colplot FAQ for more information.
AUTHOR
This program was written by Mark Seger (mjseger@gmail.com).
Copyright 2005 Hewlett-Packard Development Company, L.P.
SEE ALSO LOCAL OCTOBER 2005 GENPLOTFILES(1)
Check Out this Related Man Page
COLPLOT(1) colplot COLPLOT(1)NAME
colplot - plots collectl data using gnuplot
SYNOPSIS
colplot -plot plots [-switches]
DESCRIPTIONS
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.
PLOTS
The plots themselves are selected from the standard list (see -showplots) with -plot.
-plot
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.
SWITCHES
The remainder of the switches which are all optional fall into several categories, the first being those that select the files and time-
frames to plot and are as follow:
-dir
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.
-all
If specified all strings specified by -contains must match for a file to be seleceted for plotting.
-date from[-thru]
The starting and ending date between which files are selected for plotting. The dates must be in yyyymmdd format.
-time from[-thru]
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.
-type type
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.
-unique
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:
-adjust
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.
-filetype type
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 STD-
OUT.
-height number
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.
-nolegend number
This removes the legend from the plotting area, causing the plot to become physically wider.
-noxaxis
This removed the xaxis from the plotting area, causing the plot to become physically taller.
-thick number
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.
-width number
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 choosing -nolegend.
-xtics n
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.
-ylog
Make the y-axis logrithmic.
This set of switches deal with the plot destination when it is NOT the terminal window:
-email address
Linux only. Address to send plot file(s) to. The only syntax check is for an '@' to appear somewhere in the address string.
-filedir directory
The name of directory into which the plot file(s) will be placed. The directory must exist.
-href
Print the hrefs that would be used if run from a browser.
-incctl
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.
-pagbrk
Instead of generating a page break in a pdf file whenever a page fills, this flag will cause a page break whenever the hostname
changes.
-subject subject
Use this subject in email rather than the default.
And finally for completeness there are several types of help:
-help
Standard help.
-showparams
This is really a debugging aid, intended for developers and/or people building custom plot definitions. When specified, the plot-
ting parameters for each selected plot will be shown. Of particular value is the actual column number for each data element in each
selected file.
-showplots
List the names of all the standard plots available for use with the -plots switch.
-version
Show both the versions of both colplot as well as gnuplot.
AUTHOR
This program was written by Mark Seger (mjseger@gmail.com).
Copyright 2003-2008 Hewlett-Packard Development Company, L.P.
SEE ALSO LOCAL OCTOBER 2008 COLPLOT(1)