Manual last updated 2008-04-30
Graphviewer is a generic data
visualization tool to display a scrolling graph for a data source on
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
. 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
can display that data locally graphically. You can even set up 'proxy'
connections using ssh
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:
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
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
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:
- in the config file with the timestep
- with the TIMESTEP
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.
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
- stacked, meaning that the
data values in each data column are drawn added on top of each other,
and their sum falls in the specified min-max
range; the CPU load above is a good example for this.
- distinct, when the values
within the graph are independent of each other and each can take the
values between min-max. Such
an example would be e.g. network in/out data traffic.
It is possible to dump the screenshot of the actual graphview
window into X Window Dump image data (*.xwd
The image dump files are generated in the current directory on pressing the P key
, and are called gvNNN.xwd
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
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
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.
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