# Colgui Frequently Asked Questions

## General Questions

- What is colgui?
- What kind of systems will it run on?
- Are there any prerequisites?
- What other resources are there?

## Running colgui

- How do I get started?
- How do I generate plots for remote systems?
- How can I control the order in which plots are displayed?
- How do you make the plots bigger?
- Is there a way to better utilize screen real-estate?

## Creating and Using Custom Plots

- How do I begin?

## Operational Problems

- What does the error Xlib: connection to ":0.0" refused by server mean?
- I keep getting the error: couldn't create local socket on port: 1234
- The plot format I'm seeing doesn't show all the line labels
- I'm color blind (so am I) and the lines are too thin to see their colors`
- The plots being displayed are wider than my screen!
- I'm overriding the plottype to produce a stacked plot and I'm not seeing all the data.
- When I run colgui with a proxy, I'm getting an error that colmux couldn't create a connection back to me.
- I'm doing a radial plot and don't see any output even though the sweeper is moving
- Why am I getting an error that the number of plots exceeds the number of of plots per row?
- I want to generate a plot for lustre data using -s and was told no plots were selected.
- My plots are maxing out at the top. Now what?
- Problems with --proxy
- The logfile(s) I generate with --logfiles or --log1file don't look like collectl plot files
- Where else can I get help?

# General Questions

## What is colgui?

Colgui is a real-time plotting tool designed to generate live on one or more systems on which collectl has been installed. It is not a general purpose plotting package.

## What kind of systems will it run on?

Colgui has been developed on a linux system. It may work on other unix-based systsems but has not been tested on any.

## Are there any prerequisites?

Colgui requires the system on which it's run to be running an X-server. This version requires at least collectl V2.1.1.

## What other resources are there?

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.

# Running colgui

## How do I get started?

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 colgui and in a few seconds you should start seeing graphics.

## How do I generate plots for remote systems?

The easiest way run it against one or more remote systems is to add the --addr switch and specify the rempote address(es). Just remember that the remote system needs to have the right version of collectl installed and be able to use passwordless ssh or rsh.

Alternatively, and often more useful when consistently accessing a group of the same systems, is to build a machines 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 --machines 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.

## How can I control the order in which plots are displayed?

Plots are displayed in the order specified, first by -s and then by -p.

## How do you make the plots bigger?

The --xaxis and --yaxis 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 --plotwidth switch.

## Is there a way to better utilize screen real-estate?

Use the --geometry switch which controls the layout of the plots themselves. The default format, called normal, always starts a new row or each host. This can be changed with --geometry c which stands for compress and compresses the format such that all rows are filled. In other words, if you are only displaying 2 plots per system, in normal mode you see 2 plots per row, but in compressed 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.

Another possibility to use dense format by specifying --geometry nd. This actually means to use the normal display of one system per row but the plots themselves should be in dense 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.

Finally, use of --geometry cd 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.

# Creating and Using Custom Plots

## How do I begin?

There are several other resources available to you.

# Operational Problems

## What does the error Xlib: connection to ":0.0" refused by server mean?

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 X based application, the system you're running on isn't configured properly.

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 X client running on that system and have your DISPLAY environment variable pointing back to the system from which you came.

I typically connect from a Windows PC and use Reflection as my X client. The first thing I do on my PC is start Reflection and run the DOS command ipconfig to get my IP address. Then I connect to the machine on which I want to run colgui via putty, and upon logging in execute the command export DISPLAY=windows-address:0.0. At this point just type colgui and you should start seeing graphs.

## I keep getting the error: couldn't create local socket on port: 1234

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 --port.

## The plot format I'm seeing doesn't show all the line labels

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.

## I'm color blind (so am I) and the lines are too thin to see their colors

Add the --linewidth 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 $plotColor[] to the colors of your choice.

## The plots being displayed are wider than my screen!

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 -r (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 --xaxis and/or --plotwidth.

## I'm overriding the plottype to produce a stacked plot and I'm not seeing all the data.

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 Used Memory at 2G, Cache Memory at 1GB, Buffered Memory at 1GB and Free Memory at 2Gb, all fit very nicely on a line 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...

## When I run colgui with a proxy, I'm getting an error that colmux couldn't create a connection back to me.

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 /etc/iptables to open a port on that interface. You can then explicitly specify that port be used with the --port switch.

## I'm doing a radial plot and don't see any output even though the sweeper is moving

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 --yaxis or consider a different type of plot.

## Why am I getting an error that the number of plots exceeds the number of of plots per row?

You only get this if running with --geometry nd 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 --xaxis, change the number of plots (request less) or use a less restrictive geometry.

## I want to generate a plot for lustre data using -s and was told no plots were selected.

Lustre plot selection is special, sorry about that. The reason is that it takes more than just -s to select a plot, you may also need to specify --lustype if the default setting doesn't match the type of system (client, OSS or MDS) you're trying to generate a plot for.

## My plots are maxing out at the top. Now what?

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:

- Modify one or more standard plots in /hp/collectl/initParams.cfg
- Create one or more new plots in /hp/collectl/initParams.cfg, accessing them with -p
- Create your own custom plots and access them with -c
- Wait for me to solve this problem for you but it could be a long wait.

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.

## Problems with --proxy

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.

## The logfile(s) I generate with --logfiles or --log1file don't look like collectl plot files

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.

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.

## Where else can I get help?

There are several other resources available to you.