.\" $Header: /home/amb/procmeter/RCS/procmeter.1 2.17 1998/01/06 19:39:03 amb Exp $
.\"
.\"  ProcMeter - A performance metering/logging program for Linux - Version 2.4.
.\"
.\"  Manual page
.\"
.\"  Written by Andrew M. Bishop
.\"
.\"  This file Copyright 1994,95,96,97,98 Andrew M. Bishop
.\"  It may be distributed under the GNU Public License, version 2, or
.\"  any higher version.  See section COPYING of the GNU Public license
.\"  for conditions under which this file may be redistributed.
.\"
.TH PROCMETER 1 "January 6, 1998"
.SH NAME
procmeter \- A simple /proc based meter (like xmeter).
.SH SYNOPSIS
.B procmeter
.BR [\-h]
.BR [\-update \ u \ [lu]]
.BR [\-horizontal|\-vertical]
.BR [\-label \ <label>]
.BR [(\-log|\-logonly) \ (<filename>|syslog|\-)]
.BR [\-data \ <filename>]
.BR [\-force-spkt]
.BR [\-force-fpkt]
.BR [cpu]
.BR [cpu-user]
.BR [cpu-nice]
.BR [cpu-sys]
.BR [cpu-idle]
.BR [load]
.BR [proc]
.BR [context]
.BR [swap]
.BR [swap-in]
.BR [swap-out]
.BR [page]
.BR [page-in]
.BR [page-out]
.BR [disk]
.BR [disk-rd]
.BR [disk-wr]
.BR [intr]
.BR [mem-free]
.BR [mem-used]
.BR [mem-buff]
.BR [mem-cache]
.BR [mem-swap]
.BR [lpkt]
.BR [fpkt]
.BR [fpkt-rx]
.BR [fpkt-tx]
.BR [fpkt-coll]
.BR [spkt]
.BR [spkt-rx]
.BR [spkt-tx]
.BR [batt-life]
.BR [batt-lvl]
.SH DESCRIPTION
.I ProcMeter
Displays one or meter stripchart style meters showing how the system is
performing.  The idea for the program came from using
.IR xmeter(1)
and
.IR perfmeter(1)
and wanting a
.BR small
and
.BR simple
version for running on a Linux box.  The reason for not using xmeter is the
overhead interms of the rstatd and portmap that would be required and also the
availability of extra statistics in /proc for Linux.  The number of meters that
are displayed can be changed while the program is running.
.SH OPTIONS
The command line options available for the program are described below.
.TP
.BR \-h
A help message is printed giving a brief description of the usage of the program.
.TP
.BR \-update \ u \ [lu]
Sets the update interval in seconds (default 1 second).  The second argument is
optional and if set is multiplied by the interval to give the time between log
file updates.
.TP
.BR \-horizontal|\-vertical
Select either the horizontal or the vertical arrangement of meters.
.TP
.BR \-label \ <label>
Use the specified label instead of the hostname in the window and logfile.
.TP
.BR \-log|\-logonly \ <filename>|syslog|\-
The
.B \-log
option with a filename will open the named file for writing and append to it a
log of the current values displayed on the graph.  If the filename given is
.B syslog
then the system log is used and if the filename is \- then stdout is used. The
.B \-logonly
option does not display anything on the screen, but does log to the log file
like the -log option.
.TP
.BR \-data \ <filename>
This option allows a named pipe to be used to pass data into the program.  The
filename must be a named pipe that is always readable or another file that is
periodically updated.  A definition file with '.def' appended (instead of '.dat'
if needed) contains the information that controls how the data is displayed on
the graph.  Each line in the defintion file matches one line in the data file
(comments are allowed in the definition file only marked by a '#' in column 0).
The line must contain the name of the statistic (for the menu and command line),
the units and interval for the graph.
.TP
.BR \-force-spkt
Force the program to offer the spkt, spkt-rx, spkt-tx options even if they are
not detected as network devices.  (Linux kernels that use modules may not have
all of the network devices loaded all of the time, and thus would not be
auto-detected.)
.TP
.BR \-force-fpkt
Force the program to offer the fpkt, fpkt-rx, fpkt-tx options even if they are
not detected as network devices.
.TP
.BR cpu
.BR cpu-user
.BR cpu-nice
.BR cpu-sys
.BR cpu-idle
The amount of CPU usage by each of the categories (user, system, nice and idle)
can be displayed individualy or a total used can be shown, 20% per division.
.TP
.BR load
The system load averaged over one minute.
.TP
.BR proc
The number of processes on the system, 10 per division.  (The number of
processes is only available on Linux kernels 1.2? and higher).
.TP
.BR context
The number of context switches, 100 per division.
.TP
.BR swap
.BR swap-in
.BR swap-out
The amount of swapping that is performed can be displayed for swapping in or out
or a total, 50 per division.
.TP
.BR page
.BR page-in
.BR page-out
The amount of paging that is performed can be displayed for paging in or out or
a total, 100 per division.
.TP
.BR disk
.BR disk-rd
.BR disk-wr
The total number of disk accesses and the number of those that were reads and
writes, 25 per division.
.TP
.BR intr
The total number of interrupts, 100 per division.  This includes the timer
interrupt which always (on x86 at least) runs at 100 per second.
.TP
.BR mem-free
.BR mem-used
.BR mem-buff
.BR mem-cache
.BR mem-swap
The memory in the system can be displayed in terms of that used (not including
buffers or cached), the amount free, the amount for buffers, the amount cached
and the amount of swap used can be shown, the number of MB per division depends
on the total amount of RAM.  (Memory cached is only available on Linux kernels
2.0? and higher).
.TP
.BR lpkt
The number of network packets on local (loopback or dummy) devices, 100 packets
per division.
.TP
.BR fpkt
.BR fpkt-rx
.BR fpkt-tx
.BR fpkt-coll
The number of network packets total, received and transmitted, and collisions on
fast (ethernet and all others not in spkt) devices, 50 packets per division.
.TP
.BR spkt
.BR spkt-rx
.BR spkt-tx
The number of network packets total, received and transmitted on slow (slip,
ppp, plip, flip, isdn, ippp) devices, 5 packets per division.
.TP
.BR batt-life
.BR batt-lvl
The remaining battery life on systems that have apm enabled, as a percentage and
the battery level as one of four states high, low, critical and unknown.
.LP
If no statistics are selected then just the menu button is displayed.
.SH USAGE
When started the program will display all of the requested statistics in a set
of vertically aligned meters.  At the top (or bottom) of each of the meters is a
label that indicates the statistic that is being displayed and the units.  At
the very top (left when horizontal) of the window is a menu buton labeled with
the hostname.  By selecting items from this menu, meters are toggled, if the
meter already exists then it is removed, if not then a new meter is added to the
bottom.  In either case, the meters will all resize to allow room and make all
of the meters the same size.
.LP
The log file contains the a header line consisting of a '#' character followed
by a list of the statistics in the file separated by spaces.  The data itself is
written into the file in the same order as listed in the header comment
following the current time in seconds since the UNIX epoch.  When the displayed
statistics change, a new header line is written into the file.  The data values
are written to the file in absolute units, and do not use the same scaling as
used for the graphs themselves.
.SH X RESOURCES
The name of the class used is ProcMeter, the widget hierarchy used is
(Widget-Class:name):

 	ProcMeter
 		Paned:pane
 			MenuButton:menu
 				SimpleMenu:menushell
 					smeBSBObject:{statistic}
 					...
 			ProcMeter:{statistic}
			...

The standard X resources that can usefully be applied to the widgets are:
.TP
.BR background
The colour to use to draw the background of the Widget, specified as an X colour
name.
.TP
.BR foreground
The colour to use to draw the foreground of the Widget, specified as an X colour
name.
.TP
.BR font
The font to use for the text, specified as an X font name.
.LP
The extra resources available on each of the meters are the following:
.TP
.BR solid
A boolean value that specifies if the area under the graph is to be filled in or
just the line drawn.
.TP
.BR grid
The colour that is to be used to draw the grid lines onto the meter.
.TP
.BR gridMin
The minimum number of grid lines that are drawn on the meter, if the data
requires more grid lines, then they are added.  If this number is negative then
no grid lines are drawn, but the meter is scaled the same way as for a positive
number.  If the number of grid lines needed to cope with the data reaches 1/3 of
the height of the window in pixles then only one grid line is drawn.  This
single grid line is drawn at the level that corresponds to the height of the
window when the 1/3 limit is reached.
.TP
.BR labelPosition
The location of the label that is drawn with each of the meters.  This can take
the values -1 for a label at the bottom, 0 for no label and 1 for a label at the
top.
.LP
To set the foreground of all of the menu items to blue, use
'*menushell*foreground: blue' in the application default file.  To set just the
cpu menu item to red use '*menushell.cpu.foreground: red'.  (Note, that the
background of the individual menu items cannot be set.)
.LP
The resources can be set on the command line as well using the Xt standard
method.  The command line arguments -xrm '*menushell.cpu.foreground: red' will
do the same as putting the line in the application defaults file.  (The single
quatation marks are important here.)
.SH SEE ALSO
xmeter(1) perfmeter(1)
.SH AUTHOR
Andrew M. Bishop 1994,1995,1996,1997 (amb@gedanken.demon.co.uk)