COLMUX(1) | colmux | COLMUX(1) |
NAME¶
colmux - multiplex communications to multiple systems running collectl from a single systemSYNOPSIS¶
colmux [-command "collectl-switches... [-p filespec]]" [-address addr1[,addr2,...]|-addr filename] [-cols col1[,col2...]] | [-column num]DESCRIPTION¶
This utility gathers up data generated by collectl from multiple systems and multiplexes it into a single consolidated format. It runs in essentialy 2 distinct modes, the first is known as real-time, because data is retrieved and displayed in real time. The second is playback mode because data is played back from existing collectl data files.Specify any combination of addresses as
hostnames OR in pdsh -w format OR a filename containg a list of
hostnames/addresses, 1 per line. You MUST have passwordless ssh access to
these nodes. If a differnt username is required, be sure to specify addresses
in username@host format noting you do not have to have the same username on
each host. If specified, these usernames will override those specified with
the -username switch. rsh access is not supported.
One can specify virtally any collectl command
here, both in real-time or playback mode. Some switches may only be used
during one mode or the other and colmux will usually let you know if you
specify an invalid combination or an otherwise restricted switch. Only those
directly affecting colmux are listed below:
--from, --thru
-o time-format
-p playback-file
-P
Limit the timeframe for data being played
back, noting you can include both the from and thru times with the --from
switch if you separate then with a hyphen.
This is a "magic" switch in that it
not only tells collectl how to display dates/times (no other options are
permitted using -o other than those from the set [dDTm]), it also tells colmux
how to display dates/times too.
In single line mode, the timestamp will either come from the host system in
real-time mode OR the first host when run in playback mode. This is the most
common use/need for this switch.
In real-time/top mode this switch is not allowed since colmux simply reports the
current time of the system it is running on.
When playing back data multi-line formatted data from one or more files, a
timestamp for each interval is reported, consisting of the time of that
interval. When this switch is included, each line will be tagged with an
appropriate timestamp since on rare occasions they may not necessarily all be
identical.
This switch tells colmux to run in playback
mode. The filename should include the directory location and is usually
specified with wild cards, limiting the selected file(s) to a specific date.
When those files are on the same host (-address is not specified), they may be
for multiple hosts, but when the files are on remote hosts they must all be
for be that unique host. If the file specification includes the string TODAY
or YESTERDAY they will be replaced with *yyyymmdd* for that date.
Run collectl in plot-format. This allows one
to specificy just about any combination of subsystems since all data is always
displayed on a single line. However, due to the lack of formatting, this also
makes no sense for multi-line displays and is therefore only supported in
single-line format.
Show a brief help message and exit.
By default, colmux set the hostwidth to 8,
unless it sees something wider and for more situations this is sufficient.
However, if one specifies hostnames that are aliases of the longer hostname,
colmux has no way of knowing the real hostlengths until after it starts
receiving data from collectl and the formatting will be off if the hostnames
are longer than the default. To overcome this problem, use this switch to
force the hostname to be this size.
Change the number of lines that are displayed
for each interval in multi-line mode. The default for will determined by the
terminal size returned by the linux resize command if present. If that command
is not present the size will be initially set to 24. If -lines is greater than
the terminal size or 0, top-like behavior will not be used when in real-time
mode.
In single-line format format this controls the number of lines displayed between
headers. A value of 0 will only display the header one time.
Sometimes a remote version of collectl is
already using the default socket. This allows one to start another instance
and override that value.
This tells colmux to execute the specified
collectl command either locally or on the first remote system specified by
-address, print the associated header with the selected column(s) highlighted
and also include each column name along with its ordinal number, making it
fairly easy to make sure you've selected the right column(s).
Use this username for ALL ssh commands. It can
be overridden for specific hosts by specifying them with the -address switch
with the desired hostnames.
Display the version and exit. It will also
report if Term::ReadKey is installed and if so what its version number
is.
Introduce a delay between interval in seconds.
You can specify fractional valuess. Not using this switch will cause the
output to be displayed as fast as it can be rendered.
Move the cursor to the home position (upper
left-hand corner) of the display to use a top-like display format.
When playing back files for multiple hosts on
the local system, sometimes you do not want to play back ALL the host files.
This filter allows you to specify only those hosts which you want to process.
The format of the list of addresses is specified in the same way as -address
except that you cannot specify a filename.
Intended primarily for output that would be
redirected to a file, do not sort or include any escape sequences in the
output.
Set the sort column to this number. The column
numbering is determined by the columns returned by collectl for the requested
command. Since date/time columns are optional for non-plot data, their
inclusion will change the numbering of the columns so if you are not sure you
selected the correct column, you should first execute your command with -test
included.
You can also change the column number interactively with the RIGHT/LEFT arrow
keys IF the ReadKey module is installed (see colmux -version) OR simply type
it in followed by the <ENTER> key.
Do not highlight the selected column. This may
be useful when redirecting output to a file and you do not want the associated
escape squences to be written to it.
Reverse the default sort order. You can also
change the direction of the sort interactively with the UP/DOWN arrow keys IF
the ReadKey module is installed (see colmux -version)
OR simply type the r key and <ENTER>.
OR simply type the r key and <ENTER>.
Do not display any rows with 0 in the sort
column. You can also type z<ENTER>interactively.
Divide each column by 1000 before
display
Divide each column by 1024 before
display
Group all data together for each host by
column number(s). As with -column, you can confirm the correct column(s) have
been selected by first running with -test.
Do not show data for individual hosts, just
display the totals.
Include the totals for each column to the
right.
Set the output columns to this width,
typically used in conjunction with -col1000 or colk to allow more hosts to fit
onto the same line. It can also be used if the host names are too narrow for
column headers and you have room to display wider names.
When intially starting up and all hosts have
not yet reported any data, colmux will display a -1 to indicate no data has
been seen yet. If during processing a host fails to report in -age intervals,
the default is 2, colmux will also report a -1 indicating the data is
stale.
In some cases, there could be erroneous data
reported as negative numbers (though sometimes negative numbers are valid).
When specified, replace any negative numbers with this value.
This switch allows you to change the -1 that
is normally reported for missing or stale data to the specified value, most
commonly 0.
This switch is for generating diagnostic
information at various levels. It is actually a bit mask, whose values are
listed in the beginning on colmux itself. Perhaps the most useful value is 1
as it will cause colmux to display all the remote commands issues to each host
in the address list and can often reveal problems when things don't seem to be
working correctly
This switch was initially included in an
earlier version when remote host checking was causing problem in some cases
and by skipping those checks, colmux would run more reliably. While it is felt
that as of V3.2.0 these reashability checks are now reliable and should not be
skipped, this switch has been left in place.
By default, when a node is found to not be
reachable, colmux will remove it from its list of hosts and continue
execution. This switch will tell colmux to exit when all hosts are not
reachable.
When specified, colmux will report the
versions it finds for collectl on each node that is reachable. Naturally using
a tool like pdsh will do the same thing, but not all users have pdsh available
to them. Colmux has been found to work best with versions collectl that are at
least 3.5 as that was the version used for development. Additional testing has
been done with slightly older versions but not all have been tested and so if
there are any operational problems it is recommended to install a newer
version and see if the problem goes away.
On rare occasions, such as testing a patch to
collectl in a copy NOT in /usr/bin, you may want to tell colmux to use that
copy instead of the standard one. Use this switch to point to that copy.
Naturally that copy must exist in that loction on all systems.
By default, collectl waits up to 10 seconds
for remote instances of collectl to connect back. On slower networks or when a
very large number of instances have been started, they may fail to connect
back in time. This switch will extend that timeout, but it also requires
collectl V3.6.4 be used because earlier version do not support this
feature.
WHAT HAS CHANGED WITH VERSION 3?¶
Users of Version 2 will find this to look like a new utility though in actuality only a couple of enhancements have been made to the functionality, which include:new way to request prefacing lines with
timestamps: Simply add the desired time format using -o to the collectl
command
no longer need -w for non-plot data: colmux is smart enough to recognize
fields that end in K/M/G and convert them to the appropriate values before
sorting. However it will still display them in their original forms. Further,
you can even sort on non-numeric fields such as device names and many of the
fields reported for process data.
Yes, it is hard to believe but a number of
switches have been eliminated either because their functionality is
encompassed in other mechanisms or their function has been deemed obsolete.
-date, -mmdd, -time: time formats now handled with -o in collectl command
-hosts, -machines: use -address
-rsh: nobody uses rsh anymore
PLAYBACK MODE RESTRICTIONS¶
The most testing has been done using collectl V3.5.0 and a fair amount of testing as far back as 3.3.6. as colmux However, for optimum results and to avoid some subtle problems fixed in 3.5.0, you should try to use with the latest version of collectl, particularly if you experience unexpected behavior. Also consider -debug 1, which will show the collectl commands being executed as sometimes they may not be what you expected.EXAMPLES¶
Run collectl on 3 nodes, showing CPU, Disk and Network statistics once a second and sorted by column 1, which happens to be total cpu.RESTRICTIONS¶
colmux requires passwordless ssh between the node it is running on those it is monitoring.KNOWN PROBLEMS¶
see source codeAUTHOR¶
This program was written by Mark Seger (mark.seger@hp.com).SEE ALSO¶
http://collectl-utils.sourceforge.net/colmux.htmlDECEMBER 2010 | LOCAL |