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 ([email protected]).
Copyright 2005 Hewlett-Packard Development Company, L.P.