Provided by: collectl-utils_4.7.1-1_all 
NAME
colgui - realtime plotting for collectl on one or more systems (all must have collectl
installed)
SYNOPSIS
colgui [-switches]
colgui --machines machinesfile [-switches]
colgui --hosts pattern [-switches]
colgui --address addresses [-switches]
DESCRIPTION
Provides a grapical user interface to collectl, displaying real-time graphs for one or
more hosts. By default, plots are generated for the local system. One can specify
other/additional systems via a file containg a list of those addresses, the hosts listed
in /etc/hosts by applying an appropriate filter or by specifying a specific address or
addresses at the command line.
BASIC SWITCHES
The easiest way to get started is to use one or more of the following switches which many
people find meet most of their needs. Over time the need may arise to change the way the
display looks, modify the data collection itself, simultaneously log the data as it is
being collected or even change the way colgui connects to remotes systems. In those
situations, more advanced switches are provided.
Common Options
When first getting started, you can use the following switches to generate plots for your
local system. To generate remote plots see the following section on "Host Selection".
--i interval
The frequency at which data should be collected. This is passed unaltered to
collectl as -i.
--r rowsize
The number of plots displayed in a row before starting a new row. By default, a
new row is automatically started for each host. see --geometry to alter this
behavior.
--s subsys
Select the plots to display by the "standard" subsystems that collectl uses. This
too is passed unaltered to collectl as -s.
Host Selection
--hosts pattern
The hosts are chosen from the /etc/hosts file by executing the command "grep
pattern /etc/hosts". The display form of the hostname will be taken from the
second field if it is defined. When using "--geometry nd", the third column will
be used.
--address addresses
One or more host names, separated by spaces and quoted if necessary. If it is
desired to display a shorter hostname when "--geometery nd" is chosen, append that
synonym to the hostname separated by a colon.
-machines machinesfile
The machinesfile is a text file similar in format to the /etc/hosts file. See
below for more details on the format and how the 2nd and 3rd names (if specified)
will be used.
Alternate Plot Selection
These additional plot selection options can be used in any combination with or without -s.
-p plots
Select one or more plots, many of which can also be selected by -s. For more
information see "Plot Selection" further below.
-c plots
Select one or more custom, user developed plots. check out
/opt/colplot/examples/*cfg to see how these work...
ADVANCED PLOTTING SELECTIONS
The first set of these effect the size of individual plots and how they are displayed.
--xaxis int
Change the size of the x-axis to be n-intervals wide, where an interval corresponds
to "-i int" seconds.
--yaxis int
Change the size of the y-axis to be "int" pixels high.
--geometry [n, c, nd, cd]
Choose the display geometry. By default, everything displays in "normal" mode,
that is a new row is started for each host. In "compact" mode, each row is filled
to the number of plots specified by -r.
Dense modes, specified by adding the "d" modifier to one of the other two modes,
removes many of the elements common to each plot and displays them elsewhere,
proving more efficient use of the screen real estate, something that becomes more
important as the number of plots grows.
NOTE - colgui always generates the same number of plots for all systems. This
means that if doing detail plots where the number of network, disks, etc can in
fact be different, colgui will pad unused entries with blank plots which won't have
an active sweeper line in them.
Some of the less common plotting switches are:
--homogeneous
When colgui starts up, it queries each node for its configuration since some nodes
can have different numbers of devices or device names. When there are a large
number of nodes this can slow down the whole startup process. This switch will set
the configurations of all nodes to that of the first one querried and can
significantly speed startup. Be very careful when doing detail reporting becuase
if two systems have a different number of devices, you will either get errors or
incorrect data displayed. If any device names differ (and this is always the case
with lustre), all systems will show the same names and this can be confusing.
--plottype [l, p, b, s, r]
Line plots, the default, are displayed using connected solid lines, indexed from
the beginning Y axis value. A "point" plot, also known as a scatter plot but the
"s" was taken, is one in which the points are not connected. "Bar" plots are
vertical bars, more often associated with business graphics.
Appending the "s" to any of the first three types (I told you the "s" was taken) of
plots will produce "stacked" plots (when there are multiple values being plotted)
such that rather than each point relative to the base of the y-axis it is stacked
on top of the previous one.
Radial or "radar" plots are actually circular plots and this must be combined with
l or p and optionally s. At this time, radial plots may produce some oddly
formatted displays.
--radint num
By default, a radial plot has the same number of intervals as an "xy" plot, that is
based on the value of --xaxis. This switch allows seeing that interval
independently.
--smooth num
Some data may be presented very spikey and this allows one to provide a smoothing
value which softens those spikes.
--linewidth pixels
For those who want a wider plotting line, this is the way to go. Enter the width
in pixels.
--plotwidth pixels
This is actually the horizontal distance between points in pixels. Changing either
this or --xaxis effects the width of the plot, but this does it without changing
the number of data points that will fit on it.
Data Collection
--count num
The number of samples to collect, this is passed unaltered to collectl as -c.
--colbin path
If collectl is stored somewhere other than /usr/sbin on the target machine, use
this to specify its location. However, remember that this path will be passed to
ALL machines being monitored.
--colmuxbin path
Like --colbin, this allows you to change the location of where to look for colmux.
--lustype [cmo]
This defines what types of lustre machines are being monitored when -sl is selected
since there is no apriori way for colgui to know that. Choose any combination of
"cmo" to choose client, mds or oss noting these types of plots will be displayed
for ALL machines selected. It is passed unaltered to collectl as -L. Also be
aware that for any machines NOT configured as running lustre, at least version
1.5.3 of collectl will be required.
--nfstype [c2]
Collectl is capable of monitoring nfs clients or servers, supporting either nfs
version 2 or 3, but only 1 of the 4 combinations during any single run. By
default, it is assumed a machine is running as a v3 server. To change either the
version or to make the target machine a client, use this switch. It is passed
unalted to collectl as -O.
Data Logging
In addition to displaying plots, colgui can also be requested to log the data
simultaneously.
--logterm
Write a copy of each record received to the terminal. Naturally the speed of the
display can effect how quickly the plots can be updated.
--log1file dir
Create a file in the specified directory named for the host this is running on and
the date/time of the data collection. Each record will be preceeded by the name of
the host (or address) from which the data was collected.
--logfiles dir
Similar to log1file except now a separate file is created for each host, named for
that host as well as the date/time that the collection was started.
You can combine --log1file and --logfiles with --logterm but not each other.
If Compress::Zlib is installed, the logs will automatically be compressed. If logging to
the terminal AND a file simultaneously, compression will be turned off.
Networking
--port number
By default, colgui communicates over port 1234. This option allows you to select a
different one.
--proxy address
If colgui cannot directly connect to the target machines, one can put the "colmux"
program on a machine that can, using it as a proxy. Specify the address of that
machine with this switch.
--realaddress address
When communicating through a proxy, this machine`s address is hidden from other
machines. Enter the address that needs to be used to connect back to this machine.
--rsh
By default, colgui uses ssh for all communications. If not available but rsh is,
select this switch.
--username name
If rsh or ssh requires some username other than the one being run under, this is
the way to change it.
PLOT SELECTION
One can actually select plots in one of three ways. Using -s, one selects a default plot
that matches the associated subsystem(s). Some of these plots contain multiple y-axes so
that they can present the maximum amount of information in the minimal amount of space.
Using -p, one selects specific plots by name. These names can be either comma separated
(no whitespace) or separated by whitespace and quoted. The list of available plots can be
displayed with --showplots, some of which are those displayed via -s. Many of these plots
are actually the multi-yaxis plots broken into 2, single axis plots. A number of these
plots contain data fields not available as -s plots so it's worth familiarizing yourself
with them.
Finally, when nothing quite fits the bill, one can use custom plots, referred to by -c.
Here too one can specify one or more name, however in this case these name actual files,
whose default extensions are "cfg". These files contain user defined plots so that you
can essentially plot any data fields known by collectl!
The rules of how to define a custom plot are contained in the sample mem.cfg which can be
found in the examples directory. There are also a number of custom lustre plots that can
display a broad set of information. These can also be used as a starting point for
building your own. There are also FAQs for both colplot and colgui that may provide
addition help.
One thing to remember is that colgui and colplot actually share ALL the plots, both
standard as well as custom. This means that any custom plots constructed for colgui can
be used by colplot and visa-versa. If there appear to be problems using custom plots -
either colgui is reporting errors OR the data being displayed does't look correct, you can
also see the parameters colgui will be using to generate its plots by using --showparams,
which shows ALL plot definitions, not just custom ones.
Finally, you CAN mix -s, -p and -c in any combinations you like.
MACHINES FILE
This is a file that names the machines which are to be monitored. At minimal, it lists
one machine per line. Each entry must be an address or a name that can be resolved to an
address. Additional names may be specified, separated by whitespace.
If a second name exists, it will be used when a title is displayed on a plot. If it
doesn't exist, the value of the first field will be displayed.
When displaying plots in compressed/dense format, host names are displayed vertically. In
some cases, the names are simply too long to fit and if specified, the value of the 3rd
field will be used, otherwise the second field will be used.
USING COLMUX AS A PROXY
This is a feature that allows you to monitor systems to which you have no direct
connectivity. This is typically the case when a machine that does has connectivity isn't
configured to run X. This feature has been successfully tested in a number of
configurations but certainly not all. If you do encounter problems be sure to report
them.
To use this feature, you need to find a machine to act as a proxy and which is capable of
accessing the target machines via both rsh/ssh and a socket connection. If there are
firewalls involved they may have to be opened up, at least for a specific port which can
then be specified with "--port".
Since machines can have multiple interfaces on them, be sure to use addresses that the
machine running colmux can see. If you do encounter problems, try logging into the
machine on which colmux is running and try to run it manually using the same node list but
without --proxy. Often this will reveal connectivity/reachability problems you didn't
realize you had.
RESTRICTIONS
Requires at least collectl V1.5.6.
When displaying detail data normal/dense using --geometry nd, there is only a single title
line displayed for all systems. This means that if the devices are not the same, the
titles can be misleading. If you're not sure what you're displaying, use --showparams to
see this level of information.
AUTHOR
This program was written by Mark Seger (mjseger@gmail.com).
Copyright 2005 Hewlett-Packard Development Company, L.P.
SEE ALSO
collectl, colmux, colplot