Gstripchart Manual | ||
---|---|---|
<<< Previous | Next >>> |
The gstripchart program determines the parameters to display by reading a configuration file. The gstripchart program will look for a configuration file in the following order:
first, for a file specified on the command line,
then, for a file named gstripchart.conf in the current working directory,
then, for a file named .gstripchart.conf in the users home directory,
then, for a file named /etc/gstripchart.conf,
and finally, for a file named gstripchart.conf in the CONFDIR directory, which will usually be either /usr/share/gstripchart/ or /usr/local/share/gstripchart/.
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:
A standard X11 geometry specification of the form WxH±X±Y.
Specifies a file from which to read configuration information, overriding the normal configuration file search order described in the section called Customization.
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.
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.
Adds an application menu bar to the main window. Normally this is omitted, and the menu is popped up by right-clicking on the chart window.
Causes the display of the slider window to be suppressed.
TYPE specifies the type of display to be generated. The TYPE specifier can be one of:
gtk — use the default gtk-based graphic display;
applet — run as an applet in the Gnome panel.
The behavior of the gstripchart program is determined by the contents of the configuration file that it reads at startup. This file is located as described in the section called Customization
This configuration file contains a series of optional application-wide configuration options described in the section called Application-Wide Configuration Options, followed by a series of parameter configuration options described in the section called Parameter Configuration Options, one for each parameter to be plotted. Each of these configuration file lines is comprised of RFC-822 style "keyword: value" pairs. A comment can be included anywhere within the configuration file by putting a sharp sign (#) in the first column of each comment line, and blank lines can be used wherever they will improve readability.
Here's an example of the initial portion of a gstripchart configuration file. It begins (as all files should) with a comment describing the purpose of the file. The comment is followed by three application-wide configuration options. The first sets the chart interval to 5.000, so that the "strip" portion of the display is updated every 5 seconds. Next, the minor tick interval is set to 12 chart update periods, producing a minor tick mark on the display at one-minute intervals. Finally, the major tick interval is set to 5 minor tick periods, producing a major tick mark on the display at five-minute intervals.
# # gstripchart.conf -- # an example configuration file # for the GNOME stripchart program. # chart-interval: 5.000 minor_ticks: 12 major_ticks: 5 |
The following application-wide configuration option 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.
Specifies the time interval in seconds between updates to the chart window and slider window as described previously under the section called Options.
Specifies the time constant in seconds to be used in low-pass filtering the data displayed in the chart or slider windows as described previously under the section called Options.
Adds or omits an application menu bar to the main window.
Adds or omits the "pen" display to the main window.
Sets the number of pixels (update intervals) between minor tick marks on the gtk and applet displays.
Sets the number of pixels (update intervals) between major tick marks on the gtk and applet displays.
The second portion of the gstripchart configuration file contains a series of parameter description groups, one group for each parameter to be plotted. Each parameter group is made up of a "begin" and "end" pair of lines enclosing the remaining parameter definition lines. In addition to the "begin" and "end" statements, each parameter group must contain an equation statement, which determines the value to be displayed, and either a "color" or a "lights" statement, which determines the display format for the parameter.
For example, a very minimal parameter definition would be the following system load average parameter.
# Load -- display the system one minute load average begin: Load color: yellow equation: $load_1m end: Load |
The following keywords are available to be used to define the way that a parameter is displayed.
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. The PARAMETER-NAME is optional, but if supplied must match the PARAMETER-NAME used in the corresponding "end" statement.
Closes a parameter block introduced by the "begin" or "identifier" keyword. The PARAMETER-NAME must match any PARAMETER-NAME supplied in the corresponding "begin" statement.
An equation used to obtain the value to be plotted for this parameter.
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 (which will always be zero) is ~i.
The usual infix arithmetic operators — addition (+), subtraction (-), multiplication (*), division (/), and remaindering (%) — are available, along with parenthesis for grouping subexpressions.
Determines the color to be used in displaying a parameter. The color names and their RGB values are taken from X11/rgb.txt.
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.
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 a series of whitespace separated fields, each of which is interpreted as a floating point number.
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.
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.
Specifies whether a logarithmic or linear scale factor is to be used when plotting a parameter value.
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.
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.
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.
Normally, the gstripchart program will be built with the libgtop library linked in. The libgtop library provides a portable and well-standardized method of accessing common system performance parameters. This is the preferred method of obtaining a value to be plotted.
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 statistic values don't use the libgtop library. Instead, they 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.
<<< Previous | Home | Next >>> |
Using gstripchart | Known bugs and limitations |