/usr/share/collectl/FAQ-colgui.html

<html>
<title>Colgui Frequently Asked Questions</title>

<body>

<h1>Colgui Frequently Asked Questions</h1>
<h2>General Questions</h2>
<ul>
  <li><a href="#gen1">What is colgui?</a></li>
  <li><a href="#gen2">What kind of systems will it run on?</a></li>
  <li><a href="#gen3">Are there any prerequisites?</a></li>
  <li><a href="#gen4">What other resources are there?</a></li>
</ul>
<h2>Running colgui</h2>
<ul>
  <li><a href="#run1">How do I get started?</a></li>
  <li><a href="#run2">How do I generate plots for remote systems?</a></li>
  <li><a href="#run3">How can I control the order in which plots are displayed?</a></li>
  <li><a href="#run4">How do you make the plots bigger?</a></li>
  <li><a href="#run5">Is there a way to better utilize screen real-estate?</a></li>
</ul>
<h2>Creating and Using Custom Plots</h2>
<ul>
  <li><a href="#cust1">How do I begin?</a></li>
</ul>
<h2>Operational Problems</h2>
<ul>
  <li><a href="#ops1">What does the error <i>Xlib: connection to ":0.0" refused by server</i> mean?</a></li>
  <li><a href="#ops2">I keep getting the error: <i>couldn't create local socket on port: 1234</i></a></li>
  <li><a href="#ops3">The plot format I'm seeing doesn't show all the line labels</a></li>
  <li><a href="#ops4">I'm color blind (so am I) and the lines are too thin to see their colors</a>`</li>
  <li><a href="#ops5">The plots being displayed are wider than my screen!</a></li>
  <li><a href="#ops6">I'm overriding the plottype to produce a stacked plot
and I'm not seeing all the data.</a></li>
  <li><a href="#ops7">When I run colgui with a proxy, I'm getting an error that colmux couldn't create a connection back to me.</a></li>
  <li><a href="#ops8">I'm doing a radial plot and don't see any output even though the sweeper is moving</a></li>
  <li><a href="#ops9">Why am I getting an error that the number of plots exceeds the number of of plots per row?</a></li>
  <li><a href="#ops10">I want to generate a plot for lustre data using -s and was told no plots were selected.</a></li>
  <li><a href="#ops11">My plots are maxing out at the top.  Now what?</a></li>
  <li><a href="#ops12">Problems with --proxy</a></li>
  <li><a href="#ops13">The logfile(s) I generate with --logfiles or --log1file don't look like collectl plot files</a></li>
  <li><a href="#ops99">Where else can I get help?</a></li>
</ul>

<h1>General Questions</h1>
<a name="gen1"></a><h2>What is colgui?</h2>
<p>
Colgui is a real-time plotting tool designed to generate <i>live</i>
on one or more systems on which <i>collectl</i> has been installed.  
It is <i>not</i> a general purpose plotting package.

<a name="gen2"></a><h2>What kind of systems will it run on?</h2>
<p>
Colgui has been developed on a linux system.  It may work on other unix-based
systsems but has not been tested on any.

<a name="gen3"></a><h2>Are there any prerequisites?</h2>
Colgui requires the system on which it's run to be running an X-server.  This
version requires at least collectl V2.1.1.

<a name="gen4"></a><h2>What other resources are there?</h2>
Colgui and colplot share the same core plotting definitions and also share
a library of routines for parsing them.  In general, if you can generate
a static plot with colplot, you should be able to generate the same plot
in real-time with colgui.  See the collectl/colplot manpages and FAQs for more.

<h1>Running colgui</h1>
<a name="run1"></a><h2>How do I get started?</h2>
<p>
Colgui is configured to display a default set of plots for the 
local system at an update interval of 1 second so all you need
do is simply type <i>colgui</i> and in a few seconds you should
start seeing graphics.  

<a name="run2"><h2>How do I generate plots for remote systems?</h2>
<p>
The easiest way run it against one or more remote systems is to add the
<i>--addr</i> switch and specify the rempote address(es).
Just remember that the remote system needs to have the right version of <i>collectl</i>
installed and be able to use passwordless <i>ssh</i> or <i>rsh</i>.
<p>
Alternatively, and often more useful when consistently accessing a
group of the same systems, is to build a <i>machines</i> file 
that looks like an /etc/hosts file, that is one host
name or address per line.  When you run colgui you pass the name
of this file to it using the <i>--machines</i> switch.  When 
colgui starts, it will announce the names of the machines it's
connecting to and these should match those in your file.  If
they do not, you probably have a syntaxt error in it.

<a name="run3"><h2>How can I control the order in which plots are displayed?</h2>
<p>
Plots are displayed in the order specified, first by -s and then by -p.

<a name="run4"><h2>How do you make the plots bigger?</h2>
<p>
The <i>--xaxis</i> and <i>--yaxis</i> switches change the 
related sizes.  The y-axis is specified in 
pixels and the x-axis in terms of intervals between plotting
points which is currently set to 3, which you can also change 
the pixel width of an interval with the <i>--plotwidth</i> switch. 

<a name="run5"><h2>Is there a way to better utilize screen real-estate?</h2>
<p>
Use the <i>--geometry</i> switch which controls the layout of 
the plots themselves.  The default format, called <i>normal</i>,
always starts a new row or each host.  This can be changed 
with <i>--geometry c</i> which stands for <i>compress</i> and
compresses the format such that all rows are filled.  In other
words, if you are only displaying 2 plots per system, in <i>normal</i>
mode you see 2 plots per row, but in <i>compressed</i> mode you
will see 4 plots per row assuming you haven't changed the default.
Just be aware that this format can be very confusing because 
depending on the number of plots per system and the number of plots
per row, these may not necessarily line up as they do when a new
system starts a new row.
<p>
Another possibility to use <i>dense</i> format by specifying 
<i>--geometry nd</i>.  This actually means to use
the <i>normal</i> display of one system per row but the plots
themselves should be in <i>dense</i> format.  This means to
factor out the labels common to each host and plot.  
Try it and see what it looks like to get a better feel.
<p>
Finally, use of <i>--geometry cd</i> will not only factor out 
common labels, it will
compress plots from multiple systems to fill each row.  
This format is only available when selecting a single plot.

<h1>Creating and Using Custom Plots</h1>
<a name="cust1"><h2>How do I begin?</h2>
<p>
There are several other <a href="#gen4"=>resources</a> available to you.

<h1>Operational Problems</h1>
<a name="ops1"><h2>What does the error <i>Xlib: connection to ":0.0" refused by server</i>
mean?</h2>
<p>
There are 2 ways you can run colgui, either from a display
directly connected to the Linux machine on which colgui is to be
run OR from a remote system connected to that Linux machine by
either a telnet or ssh session.  In both cases, since colgui is an <i>X</i> 
based application, the system you're running on isn't configured properly.
<p>
If you are directly attached to the system, it must be
operating in graphics mode, which is easily identified because
it will be running a graphical desktop.  If you have connected via a remote
terminal session, you must have an <i>X</i> client running on that system
and have your <i>DISPLAY</i> environment variable pointing back to the system
from which you came.  
<p>
I typically connect from a Windows PC and use <i>Reflection</i> as my X client.
The first thing I do on my PC is start <i>Reflection</i> and run the DOS 
command <i>ipconfig</i> to get my IP address.  Then I connect to the machine on
which I want to run <i>colgui</i> via <a href=http://www.chiark.greenend.org.uk/~sgtatham/putty/><i>putty</i></a>, and upon
logging in execute the command <i>export DISPLAY=windows-address:0.0</i>.  At
this point just type <i>colgui</i> and you should start seeing graphs.

<a name="ops2"><h2>I keep getting the error: <i>couldn't create local socket on port: 1234</i></h2>
<p>
By default, colgui uses socket 1234 for connections.  It may be possible that
some other application is already using that socket OR a previous instance of
colgui existed abnormally leaving that socket open.  In either case, rereun
colgui and specify a different value using <i>--port</i>.

<a name="ops3"><h2>The plot format I'm seeing doesn't show all the line labels</h2>
<p>
You can either make the plot wider so the labels will fit or look at the 
terminal window from which you started colgui.  There is a table that lists
the plot colors and associated labels.

<a name="ops4"><h2>I'm color blind (so am I) and the lines are too thin to see their colors</h2>
<p>
Add the <i>--linewidth</i> switch along with a number that 
specifies the line widths in pixels to make them wider and 
therefore brighter.  A setting of 2 or 3 is usually adequate for me.  
Alternatively, you could modify the default color scheme in the
code itself by setting the variables 
<i>$plotColor[]</i> to the colors of your choice.

<a name="ops5"><h2>The plots being displayed are wider than my screen!</h2>
<p>
By default, a new row of plots is displayed for each system 
being monitored.  The number of plots displayed in one row 
is controlled by <i>-r</i> (number of plots per row) and 
currently set to 4.  You can either set this to a smaller number
OR simply reduce the width of the individual plots by using
<i>--xaxis</i> and/or <i>--plotwidth</i>.

<a name="ops6"><h2>I'm overriding the plottype to produce a stacked plot 
and I'm not seeing all the data.</h2>
<p>
This can happen if the y-scale is set such that it is smaller 
than the total of the stacked values.  For example, if you have 
a memory plot with a y-scale of 4GB and it shows 
<i>Used Memory</i> at 2G, <i>Cache Memory</i> at 1GB, 
<i>Buffered Memory</i> at 1GB and <i>Free Memory</i> at 2Gb, all
fit very nicely on a <i>line</i> graph since none of the values
exceed the y-axis maximum value.  However if you stack these
you get total values of 6GB and so one or more lines will be off
the charts!  This is not a bug...

<a name="ops7"><h2>When I run colgui with a proxy, I'm getting an error that colmux couldn't create a connection back to me.</h2>
<p>
Something is preventing the reverse connectivity problem.  That has been seen
when the host system is running a firewall that doesn't have a rule to allow 
incoming TCP connections on that interface/port.  You will either need to 
change the interface being used to one that is open or change the definitions 
in <i>/etc/iptables</i> to open a port on that interface.  You can then 
explicitly specify that port be used with the <i>--port</i> switch.

<a name="ops8"><h2>I'm doing a radial plot and don't see any output even though the sweeper is moving</h2>
<p>
By the nature of the number of pixels near the center of this type of plot, 
low values often don't have enough pixels to represent them and they appear 
invisible.  Either make the plot a lot bigger via <i>--yaxis</i> or consider 
a different type of plot.

<a name="ops9"><h2>Why am I getting an error that the number of plots exceeds the number of of plots per row?</h2>
<p>
You only get this if running with <i>--geometry nd</i> which by definition 
always places all plots for the same host on the same row.  In this case 
they won't all fit and the only solutions are to make the row wider (and 
some plots may go off the screen), make the plots narrower using 
<i>--xaxis</i>, change the number of plots (request less) or use a less 
restrictive geometry.

<a name="ops10"><h2>I want to generate a plot for lustre data using -s and was told no plots were selected.</h2>
<p>
Lustre plot selection is <i>special</i>, sorry about that.  The reason is 
that it takes more than just -s to select a plot, you may also need to 
specify <i>--lustype</i> if the default setting doesn't match the type of 
system (client, OSS or MDS) you're trying to generate a plot for.

<a name="ops11"></a><h2>My plots are maxing out at the top.  Now what?</h2>
<p>
By design, all the standard plots have their maximum values defined in 
/opt/hp/collectl/initParams.cfg.  In the case of network detail plots, colgui can
often tell the maximum interface speeds from collectl. In the case of summary
plots if the limit is chosen at their aggregate peaks, this will often be
too high.  The problems can be even worse with many disks, particularly if runing
with storage arrays which can look like a single disk and yet perform at many times
a single disk's rates.  Therefore a reasonable guess was taken at choosing the
defaults.  If this does not meet your needs, you have several choices:
<ul>
  <li>Modify one or more standard plots in /hp/collectl/initParams.cfg</li>
  <li>Create one or more new plots in /hp/collectl/initParams.cfg, accessing them
      with -p</li>
  <li>Create your own custom plots and access them with -c</li>
  <li>Wait for me to solve this problem for you but it could be a long wait.
</ul>
<p>
While certainly the easiest to do, the danger with the first two choices is that
you will need to carry these changes forward with each new release and since all
you're doing at this time is creating custom plots, you might as well as choose
the third option.

<a name="ops12"><h2>Problems with --proxy</h2>
Using --proxy can be tricky if not all versions of collectl are consistent across
all nodes being monitored.  Rather than going into a lot of details about why, make
sure all nodes are running the same version and try again.

<a name="ops13">
<h2>The logfile(s) I generate with --logfiles or --log1file don't look like collectl plot files</h2>
There are a couple of possibilities here.  Logfiles generated using versions of
collectl prior to 2.0 will not provide the necessary header information.  If
you want data plottable by colplot be sure to use a newer version of collectl.
<p>
By definition, --log1file puts all data into 1 big file, each line prefaced by
the node number of the host that generated the data.  In order to plot this 
data you must separate the data back into separate files and remove the host
numbers from the first column.

<a name="ops99"><h2>Where else can I get help?</h2>
<p>
There are several other <a href="#gen4"=>resources</a> available to you.

</body>
</html>
collectl-utils 4.7.1-1 / usr / share / collectl / FAQ-colgui.html
