GNOME Stripchart Documentation

The GNOME stripchart program charts various user-specified parameters as a function of time. Its main use is to chart system performance parameters such as CPU load, CPU utilization, network traffic levels, and the like. Other more ingenious uses are left as an exercise for the interested user.

The gstripchart program periodically reads data from a file, extracts a value, and displays these values in one of several formats. The default format is a graphical display similar to that of a stripchart recorder. Hence the name, "gstripchart".

On systems such as Linux, in which the system parameters are available in human-readable form in the /proc directory, the gstripchart program makes a dandy performance monitoring tool, similar to but more versatile than xload.

Instead of being limited to a few standard performance parameters, the gstripchart program can plot any time-variant parameter than can be read from a file or pipe. This ability to read data from a pipe provides a very versatile and easy to use method of setting up custom displays.

The gstripchart program determines the parameters to display by reading a configuration file. The gstripchart program will first look for a configuration file specified on the command line, then look for a file named gstripchart.conf in the current directory, then look for a file named .gstripchart.conf in the users home directory, then look for a file named /etc/gstripchart.conf. If no configuration file is found, the program displays an error message and exits.

Options

There are a few command line switches that can be used to alter the behavior of the program. In addition to the common help, usage, version, Gnome, Gtk, and Session management options, the following gstripchart-specific options are available:
  -g, --geometry=GEO               Geometry string: WxH+X+Y
  -f, --config-file=FILE           Configuration file name
  -i, --chart-interval=SECS        Chart update interval
  -I, --chart-filter=SECS          Chart low-pass filter time constant
  -j, --slider-interval=SECS       Slider update interval
  -J, --slider-filter=SECS         Slider low-pass filter time constant
  -M, --menubar                    Adds a menubar to the main window
  -S, --omit-slider                Omits slider window
  -t, --display-type=TYPE          Type of display to generate
    TYPE is one of:
      none:   no display is produced (for debugging);
      text:   a textual numeric display is produced;
      graph:  a textual graphic display is produced;
      gtk:    use the default gtk-based graphic display;
      applet: run as an applet in the Gnome panel.
config-file filename
Specifies a file from which to read configuration information. If unspecified, the current working directory is checked for a file named "gstripchart.conf", the user's home directory is checked for a file named ".gstripchart.conf", and the /etc directory is checked for a file named "gstripchart.conf". The first such file found is used.
geometry geometry-spec
A standard X11 geometry specification of the form WxH+X+Y.
chart-interval update-interval
slider-interval update-interval
Specifies the time interval in seconds between updates to the chart window and slider window. If unspecified, the chart window will be updated every 5 seconds and the slider window will be updated every 0.2 seconds.
chart-filter time-constant
slider-filter time-constant
Specifies the time constant in seconds to be used in low-pass filtering the data displayed in the chart or slider windows. A time constant of 0 seconds turns low-pass filtering off, which can result in a jumpy display. A time constant in the same range as the interval parameter, described above, is usually a good choice. Much larger values cause display updates to become sluggish. If unspecified, no low pass filtering is performed in either window.
menubar
Adds an application menubar to the main window. Normally this is omitted, and the menu is popped up by right-clicking on the chart window.
omit-slider
Causes the display of the slider window to be suppressed.

Configuration

The configuration file has a paragraph of configuration information for each parameter to be ploted. Each of these paragraphs are comprised of a series of RFC-822 style "keyword: value" pairs, beginning with an "identifier:" line. A comment can be included by putting a sharp sign (#) in the first column of a line.

The following keywords are available. Some are optional; some are only used by certain display types; many have reasonable default values, as described below.

The first group of keywords provide the same functions as the command line switches described in the previous section. The options in this group must be placed at the beginning of the configuration file, prior to the parameter definition section. If a value is supplied for any of these parameters both in the configuration file and on the command line, the command line value takes precedence.

chart-interval: update-interval
slider-interval: update-interval
The same as the chart-interval and slider-interval command line switches described previously.
chart-filter: time-constant
slider-filter: time-constant
The same as the chart-filter and slider-filter command line switches described previously.
menu: yes-or-no
slider: yes-or-no
Enables or disables the menu bar and slider window.
minor_ticks:
Sets the number of pixels (update intervals) between minor tick marks on the gtk and applet displays.
major_ticks:
Sets the number of minor tick marks to display between major tick marks on the gtk and applet displays.

Parameters

The following keywords are used to define the parameters that are displayed.

begin: parameter-name
identifier: parameter-name
Introduces a parameter definition, and assigns a name to the parameter. This line must be the first line of a parameter description. The "begin" and "identifier" keywords are synonymous.
end: parameter-name
Closes a parameter block introduced by the "begin" or "identifer" keyword.
active: yes-or-no
If a parameter is marked "active: no", it will not be displayed. This provides a convenient way to disable a parameter without deleting it from a parameter file.
id_char: character
Provides a single-character abbreviation for a parameter. Currently unused, this is intended for the non-existant character-graphics display mode.
color: color-name
Determines the color to be used in displaying a parameter. The color names and their RGB values are taken from X11/rgb.txt.
lights: color-name [, color-name ...]
If a parameter block contains a "lights:" line instead of a "color:" line, the parameter will not be plotted. Rather, a small square in one of the supplied colors is displayed near the upper-left corner of the display. The color used is based on the value of the parameter. A value of less that 0.5 leaves the light in the background color; a value between 0.5 and 1.5 displays a light in the first color; a value between 1.5 and 2.5 displays a light in the second color; and so forth for as many colors were supplied on the "lights:" line.
filename: path
The file from which a parameter value is read. When a filename beginning with a "|" is supplied, input lines will be read from a pipe.
pattern: string
The pattern which identifies the line from which a parameter value is to be extracted. If no pattern is provided, the first line of the file is used.
fields: number
Deprecated. This used to be used to specify the number of fields to be split out of the first line which matches the pattern, with splitting being done on whitespace. This is now calculated as the highest-numbered field used in the equation.
equation: eqn
An equation used to obtain the value to be ploted for this parameter.
scale: log-or-linear
Specifies whether a logarithmic or linear scale factor is to be used when plotting a parameter value.
maximum: number
The largest value that can be displayed. Any value in excess of the maximum will be plotted at the top of the display. If omitted, a default value of 1.0 is used.
minimum: number
The smallest value that can be displayed. Any value less than the minimum will be plotted at the bottom of the display. If omitted, a default value of 0.0 is used.

On each iteration, a value to be displayed is obtained for each parameter in the configuration file. The file named in the "filename" line is opened -- either as a pipe if the filename begins with a pipe character (|), or as a regular file otherwise -- and a line is read.

If a pattern was specified, lines are read until one is found that contains the pattern string anywhere in the line. This line is split into the number of whitespace seperated fields specified in the "fields" line. Each of these fields is interpreted as a floating point number.

A value is obtained by evaluating the "equation" line using these field values. The first (or only) value is denoted by $1, the next by $2, and so forth. The difference between the field values between the last and the current iteration is denoted by ~1, ~2, and so forth. The elapsed time in seconds between the last and current iteration is ~t. The requested update interval is $i (and the delta is ~i, but will always be zero). All the usual infix arithmatic operators are available.

libgtop

If libgtop support has been compiled into the gstripchart program, a value can be obtained from this library. This provides a portable method of obtaining many system performance parameters. The following libgtop parameters are available:

CPU Statistics
cpu_total, cpu_user, cpu_nice, cpu_sys, cpu_idle, and cpu_freq
Memory Statistics
mem_total, mem_used, mem_free, mem_shared, mem_buffer, mem_cached, mem_user, mem_locked
Swap Statistics
swap_total, swap_used, swap_free, swap_pagein, swap_pageout
Uptime Statistics
uptime, idletime
Loadavg Statistics
load_running, load_tasks, load_1m, load_5m, load_15m
Network Statistics
net_pkts_in, net_pkts_out, net_pkts_total, net_bytes_in, net_bytes_out, net_bytes_total, net_errs_in, net_errs_out, net_errs_total

Note that the network statistics don't use the libgtop library. Instead, the values are read directly from /proc/net/dev, and so are only available under Linux.

These are all signed long integer quantities, except for uptime, idletime, and the five load values which are floating point values.