## stripchart

2000, 2001
John Kodis

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found here.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.

This is version 1.0 of the stripchart manual.

## Introduction

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. It is included in the package `gnome-utils`, which is a part of the GNOME desktop environment. This document describes version &version; of the stripchart program.

The stripchart 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, stripchart.

### Stripchart Plotter Main Window

Stripchart Plotter Main Window

On systems such as Linux, in which system parameters are available in human-readable form in the /proc directory, the stripchart 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 stripchart 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 stripchart program is available both as a stand-alone program, and as a Gnome panel applet. The program can be started by selecting Stripchart Plotter item from the Utilities submenu of the Main Menu, by selecting Stripchart Plotter item from the Monitors submenu of the Gnome panel Applets, or by running the command `stripchart` or `stripchart-applet` from the command line.

### Stripchart Plotter Applet Window

Stripchart Plotter Applet Window

## Using stripchart

Although the stripchart program can be used to plot very nearly any parameter that is of interest, the default configuration will produce a useful overview of the performance parameters of the system that it's being run on. This section describes basic usage of the stripchart program in its default configuration. A description of how to customize the parameters that are plotted is provided later in this document.

When you first start stripchart, you see the main window, as shown in or in .

### Stripchart Plotter Main Window

Stripchart Plotter Main Window

### Stripchart Plotter Applet Window

Stripchart Plotter Applet Window

In its default configuration, the stripchart program creates a 200 by 50 pixel window that contains two main elements — a scrolling "strip" on the left, and a series of "pens" on the right. The stripchart applet is similar, but its size adapts to the size of the panel in which it is run. When using the default configuration, there will be a "pen" and a "strip" line showing the current and recently past values of system's CPU utilization in blue, the one minute load average in yellow, the percentage of swap space in use in white, and the inbound and outbound network traffic volumes in red and green, respectively. If a PPP interface is currently active, a green indicator light will be displayed in the upper left corner of the main window.

Clicking on the stripchart main window with mouse button one will pop up a numeric value window. The numeric value window corresponding to the main window shown in the previous figures is shown below in .

### Parameter Numeric Value Window

Parameter Numeric Value Window This window provides a multi-line, text-based display of the name, current value, full-scale value, and scaling (linear or logarithmic) of each of the parameters being plotted. It can be dismissed either by clicking on the close button in the title bar of the numeric value window, or by a second mouse click in the main window.

Clicking on the stripchart main window with mouse button three will pop up an Application menu containing Help, About, Show values, Edit Prefs, Edit Params, and Exit menu items, as shown below in .

### Main Window with Pop-Up Menu

Main Window with Pop-Up Menu The Help and About menu items display this help information and the usual about box, respectively, and the Exit menu item terminates the execution of the stripchart program. The Show values menu item will pop up a numeric value window, as described above.

The operation of the stripchart application can be customized by editing the application preferences and the parameters that are plotted. The Edit Prefs menu item displays an application preferences editing window, as shown in . The settings in the Preferences Window are described in .

### Preferences Window

Preferences Window

The Edit Params menu item displays a window containing a notebook with a page describing the details of each parameter, as shown in . Parameters can be edited as described in .

### Parameter Window

Parameter Window

## Command-Line 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 stripchart-specific options are available:

--geometry GEOMETRY-SPEC

  A standard X11 geometry specification of the form WxH±X±Y.

--config-file FILENAME

  Specifies a file from which to read configuration information, overriding the normal configuration file search order described in . You can change the parameters monitored by an instance of the stripchart program by specifying an alternate configuration file.

## Preference Settings

The Preferences Window provides a way to adjust settings which have an effect on the overall operation of the stripchart program. Separate sets of controls are provided for the operation of the pens and for the operation of the main chart window.

### Preferences Window

Preferences Window

Both the chart and the pens have their own adjustments for the update interval and for the level of smoothing to be performed. The update interval determines how frequently a new set of data points should be collected and displayed. This defaults to once per second for the pens, and once every 5 seconds for the chart lines. The smoothing value determines how sharp of a low-pass filter should be applied to the raw data values prior to displaying them. This value defaults to 0.5 for both the pens and the chart lines. Setting the smoothing to zero eliminates this filtering of the raw data, resulting updates which are more responsive but which can appear jumpy or jagged. Setting the smoothing to one freezes the current values in place. Intermediate values generate a new plot value by taking the difference between the last value and the new raw parameter value, multiplying by the smoothing constant, and adding this to the last value.

The chart portion of the Preferences Window also has a check-box to enable or disable the display of tick marks along the time axis of the stripchart display. When the display of tick marks is enabled, the intervals between minor and major tick marks can be adjusted. The default settings provide for a minor tick mark every twelve pixels and a major tick mark every five minor tick marks. With the default five second chart update interval, these values will place a minor tick mark every minute and a major tick mark every five minutes.

The pen portion of the Preferences Window provides a check-box to enable or disable the display of the pen portion of the stripchart display. While the pens provide a rapidly updating view of the parameters being monitored, this constant motion could become distracting. Adjust to taste.

The standard "Okay", "Apply", and "Cancel" buttons are available to apply new settings and close the Preferences dialog window, to apply new settings without closing the Preferences dialog window, and to close the Preferences dialog window without altering the current preference settings, respectively.

## Parameter Settings

The parameters displayed by the stripchart can be examined and edited using the Parameter Editor window. Although stripchart provides great potential for adding custom parameters, most users will initially be satisfied with the selecting from the list of pre-configured parameters supplied. Adding or deleting these parameters is described in .

### Parameter Window

Parameter Window

### Parameter Editor Quickstart Guide

To delete one of the currently active parameters:

- Select the parameter to be deleted by clicking on its tab at the bottom of the Parameter Editor window;

- Select the Edit menu item;

- Select the Delete Parameter menu item.

To add one of the pre-defined parameters:

- Select the Edit menu item;

- Select either the Add Parameter Before or the Add Parameter Before menu item to insert a new empty parameter page;

- Select one of the pre-defined parameters from the parameter itemlist on the "Parameter" line of the page. This will fill in the required fields for the newly created parameter, and begin plotting it.

### Creating Custom Parameters

The creation of a custom parameter can be done by editing an existing parameter, by adding a new parameter and editing it, or by adding a new parameter and filling in the parameter fields from scratch. Many of the parameter fields can be left blank. While good style dictates that a parameter name and description be provided for documentation purposes, the only mandatory fields are those required to obtain a value to be plotted. Generally, the Equation field will fill this role. The details of each of these fields are described below.

Parameter

  A short descriptive name for the parameter.

Description

  A longer description of the parameter.

Filename

  The name of a file from which equation parameters are obtained. On each iteration, a line is read from this file. If a pattern was supplied, 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. The first (or only) value is denoted by $1, the next by $2, and so forth. The difference between the field values from the previous to the current iteration is denoted by ~1, ~2, and so forth.

  If a filename beginning with a "|" is supplied, input lines will be read from a pipe instead of a file. Lines read from this pipe will be processed identically to lines read from a file as described previously.

  If a filename beginning with a "?" is supplied, the file status determines the value to be plotted: -1 for a non-existent file, 0 for a file of zero length, 1 for a file with an access time that is newer than its modification time, and 2 for a file with a modification time that is newer than its access time. These values are useful in displaying the status of a mailbox file.

Equation

  An equation used to obtain the value to be plotted for this parameter. The equation is made up of parameters which are combined using the usual infix arithmetic operators.

  There are several sources for equation parameters.

  - The parameters can be obtained by reading a line from a file. This method of obtaining equation parameters is described under the previous Filename section.

  - There are a number of built-in parameters. The elapsed time in seconds between the last and current iteration is ~t. The elapsed time in seconds since the stripchart program was started is $t.

  - There are a number of parameters provided by the libgtop library. These are described in .

  The usual infix arithmetic operators — addition (+), subtraction (-), multiplication (*), division (/), and remaindering (&percnt;) — are available, along with parenthesis for grouping subexpressions, and unary minus (-) to negate a value. Grouping and negation have the highest precedence; multiplication, division, and remaindering have the next highest precedence; and addition and subtraction have the lowest precedence.

Pattern

  If the filename field specifies a file containing more than a single line of text, the pattern field can be used to select the line from which equation parameter values will be obtained. Lines will be read from the file until a line containing the specified pattern is found, or until the end of file is reached. If no pattern is provided, the first line of the file is used.

Top Min
Top Max
Bottom Min
Bottom Max

  The minimum and maximum to be used for the value at the top and bottom of the chart.

Scale

  The type of scaling to be performed on the parameter values before they are plotted: either linear or logarithmic.

Type

  The type of plot to be generated for this parameter value. The value can be plotted as an indicator, a small square in the upper left corner of the window; as a line drawn between successive parameter values; as a point for each parameter value; or as a solid, with the area below each parameter value solidly filled in.

Color

  The color or colors to be used when plotting this parameter value. For an indicator plot, a series of colors are used, the first for parameter values of one, plus or minus one-half, two, plus or minus one-half, three, plus or minus one-half, and so on. For line, point, and solid plot types, only a single color is used.

### libgtop Values

Normally, the stripchart 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.

## Configuration and Parameter Files

The stripchart program determines the parameters to display by reading a configuration file. The stripchart 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 `stripchart.conf` in the current working directory,

- then, for a file named `.stripchart.conf` in the users home directory,

- then, for a file named `/etc/stripchart.conf`,

- and finally, for a file named `stripchart.conf` in the CONFDIR directory, which will usually be either `/usr/share/stripchart/` or `/usr/local/share/stripchart/`.

If no configuration file is found, the program displays an error message and exits.

The canned parameters that are displayed in the Parameter Editor window are read from the `stripchart.param` file in the `{prefix}/share/stripchart` directory.

## Known bugs and limitations

The --geometry option doesn't interpret negative position arguments correctly.

The network traffic parameters are only available under Linux.

## Authors

The Stripchart Plotter was written by John Kodis (kodis@jagunet.com). Please send all comments, suggestions, and bug reports to the GNOME bug tracking database. (Instructions for submitting bug reports can be found on-line.) If you are using GNOME 1.1 or later, you can also use Bug Report Tool (`bug-buddy`), available in the Utilities submenu of Main Menu, for submitting bug reports.

This manual was written by John Kodis (kodis@jagunet.com). Please send all comments and suggestions regarding this manual to the GNOME Documentation Project by sending an email to docs@gnome.org. You can also add your comments online by using the GNOME Documentation Status Table.

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

    Free Software Foundation, Inc.  59 Temple
        Place - Suite 330 Boston, MA
        02111-1307 USA