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