Graphviewer manual

  Manual last updated 2008-04-30

General

Graphviewer is a generic data visualization tool to display a scrolling graph for a data source on stdin.

The usage principle is that you start a program that produces data series in columns on its standard output (e.g. vmstat) and then pipe it's output into graphview.

When you start graphview, you specify a config file (*) that describes which columns of the data series you are interested in.
Then you also describe data range, graph type, labels for the legend, color, and you're ready to go.
graphview will display the data as a scrolling graph, like the OpenView perfmeter or KDE sysguard.

(*) Actually I was lying :) - you can specify several config files for the same input source (i.e. invocation of graphview), and in that case you get as many graph windows as many config files. This can be used to display data values with different value ranges in different graphs (e.g. vmstat memory usage and CPU load) that would not look sane in the same graph.
Each window gets the name of its config file as title, unless the WINDOW_TITLE environment variable is set, in which case all windows get that as title.

You can find fully documented examples with all the supported specification options in the files under config.
If you don't want to write the config file manually, you may use the online config file generator.

The main feature of graphview is - as can be understood from the above - that it's generic, as opposed to other graph display tools that use proprietary system interfaces, e.g. they query the system load via rstatd. More than that, it is generic also across hosts, so if you run a data source on the target machine with e.g. ssh, you can display that data locally graphically. You can even set up 'proxy' connections using ssh's port forwarding; you can do cross-platform graph display (e.g. command line logging in to another OS),  so use your imagination, get acquainted with a scripting tool, and there will be no limit :)

Usage and behaviour

The GUI is rather simple; it's a non resizeable window per graph, displaying a scrolling graph like this:

graphview screenshot

The graph is scrolled left by one column (of pixels) whenever a new line of data is received on stdin. This means that  input sources that flush their stdout only after a bunch of lines may cause uneven scrolling behaviour, i.e. nothing happens for a while, then the graph is scrolled with quite a bit, as several lines of data are received at the flushing.
If you write your data source on your own, it's wise to flush the stdout per line. In the GNU awk you can use fflush() for this.

The tooltip for the graph area will show the minimum and maximum values for the graph. If you click on a position, a horizontal and a vertical ruler is drawn across that point and the corresponding X offset and Y value is shown in the graph title as long as the mouse button is pressed:

graphview rulers

In the example above, the click was made at a graph column that belongs to a data sample received 55 s ago, and the value clicked is 47 (in this case it means 47% on a 0-100 % CPU load scale).
Of source it is only meaningful to display seconds as time offset if the data is received at regular intervals (as is the case with vmstat). You can specify the interval in 2 ways:
Both contain the time step value in seconds, and the environment variable takes precedence if specified. If neither are defined, then the X ruler offset is displayed without unit, meaning the column distance from the right (most recently drawn) edge.

Graph data

The format of the input data rows is integers (or floats that will be converted to integers by truncating the part after the decimal point).
You can select any number of values from a data row to be displayed in one graph, with the limitation that their value range is the same. Example: CPU user/kernel/IO wait load can fit into one graph (see the screenshots above) as they both fall into the 0-100 range.
Graph type can be

Screen dump

It is possible to dump the screenshot of the actual graphview window into X Window Dump image data (*.xwd) files.

The image dump files are generated in the current directory on pressing the P key, and are called gvNNN.xwd where NNN is a running index started from 000 each time when graphview is started and incremented each time when P is pressed. This is also valid if you run several graph windows. Then it's your task to separate the xwd files for different graph windows.

Note that if the window's rectangular area is partly covered by some other object on the screen, that will be visible in the screen dump. So raise the graph window to dump to the top before pressing P.

Exit

When EOF is detected on stdin, graphview exits, but before that a popup window appears with a button that must be pressed before the graph windows are closed. This is in order to be able to see/grab the last snapshot for the case when e.g. the input source is run remotely on another machine and that crashes or exits for some reason but you want to see the last state.

Feedback

If you want to send bug report, please run graphview with setting the GVDEBUG environment variable to 1 and then redirect the stderr into a file. Bug reports, improvement ideas should be sent to