OmniMoni(1)

NAME
omnimoni - a highly configurable, realtime, information monitoring system

SYNOPSIS
omnimoni [--d debug-level] [--i indent-char(s)] [--r rc-filename] [--u milliseconds] [-help] [--help] [--legal]

DESCRIPTION
OmniMoni is a program written in Tcl/Tk and therefore requires a Tcl/Tk interpreter, usually wish. It displays periodically updating textual messages and solid or lined graphs, in a user configurable format within an X window.

OmniMoni is "told" what information to display and how to display it by parsing a configuration file (usually ~/.omnirc). The format for this file is described below in the OMNIRC section.

OmniMoni was written out of frustration at not being able to find utilities to monitor all the information I wanted. Also, once I'd managed to find a number of monitoring programs that began to serve my purposes there was always some part of them that I did not like. Additionally, I usually ended up have quite a few of these monitoring programs opened on my X display at any given time creating clutter.

The hope behind OmniMoni is to give almost complete control of the what information is monitored, when it is monitored, and how it is displayed to the user. Included in this is the powerful function of "unpacking" and "repacking" any individual item. Ideally, OmniMoni will meet all of the monitoring needs of most users.

ENVIRONMENTAL VARIABLES
OmniMoni will look for the following optional environmental variables:

OMNIMONI_RC
    Specifies the configuration file. The default is ~/.omnirc.

OMNIMONI_INDENT
    Specifies the indent character(s) used in debug level 2 (see the --d subsection of the OPTIONS section below).

OMNIMONI_DELTA
    Specifies the update time in milliseconds which OmniMoni will check to see if any dynamic labels require updating. The default is 1000 (1 second).

OPTIONS
OmniMoni requires no command line arguments but does recognize the following options:

--d debug-level
    Specifies which debugging information to produce to standard out. There are currently 6 separate types of debugging information. This gives a total of 64 possible debugging levels. In order to use more than one debug level at the same time, you would add the level numbers together. Thus to display all levels simultaneously, you would use debug level 63 (1+2+4+8+16+32). The debug level can be changed interactively by typing certain numbers (see the Changing the Debug Level subsection of the USAGE section). The levels are as follows:

    1   This level displays information about what is happening when OmniMoni is parsing the configuration file. It also displays what is happening when parsing the internal stripped configuration file while it is running.

    2   This level displays the stripped configuration file as it is parsed initially. After the initial setup this level produces no more output. The output from this level can be redirected to a file and be easily and nicely formatted via brace indentation. Emacs (in tcl-mode) does this quite well.

    4   This level produces no output but causes all labels to be static. So, instead of producing the output from the given programs (see the Group subsection of the OMNIRC section below), this will show the pointers to that output.

    8   This level shows what widgets are being upacked and repacked as it happens. It is not particularly useful, but if you are having trouble with too many groups, this can help explain what is going on.

    16  This level shows the actual Tcl/Tk error message if an error occurs. If you run OmniMoni and an error occurs, but that error is does not give you enough information, you can try rerunning with debug level 16 and see the full error message. Note that this can sometimes produce a great deal of output.

    32  This level shows what variables are set and what value they are set to. If a variable is set multiple times this will appear multiple times.
Note that the debug level can be changed interactively while OmniMoni is running (see the USAGE section below).

--i indent-character(s)
    Specifies what character or characters to use for each level of indentation for debug level 2 output. The default is " " (four spaces).

--r rc-configuration-file
    Specifies what rc file to load for determining the information to monitor. The default it ~/.omnirc (i.e., the file .omnirc in the user's home directory).

--set variable-name value
    Specifiies the value for a given variable. A variable name must be only capital letter (A-Z). The value can be anything but if whitespace is involved then it should be enclosed in quotes.

--u update-in-milliseconds
    Specifies how often to recheck for possible field updates. To have OmniMoni use a minimum of system resources, this number should be as large as possible and still give you satisfactory results. The default is 1000 (1 second), this is generally too small.

-help
    Displays command line arguments that wish accepts. This assumes the Tcl/Tk interpreter being used is wish.

--help
    Displays detailed list of OmniMoni options.

--legal
    Displays the legal and copyright information regarding the release of OmniMoni. This information is the same as that specified in the section LEGAL later in the manual page.

USAGE
While OmniMoni is running there are a number of operations the user can perform. The following functions are available:

Demand Update
    By clicking with the left mouse button on any dynamic widget label (clicking on a static widget has no affect) you will set the next update time for that widget, and all its ancestors, to zero. Then OmniMoni will go through the internal configuration file determining who now needs to be updated. This method will produce an update for all siblings of the selected widget. By sibling I mean any labels at the same level with the same parent. This operation can sometimes take a few seconds before the text is updated due to the speed of the machine and the current load and the size of the configuration.

Scrolling Graphs
    By pressing the left mouse button on any graph and then moving the mouse while the button is still depressed, you can scroll the graph forward or backward (in reference to the direction of that graph) up to the size of the history of that graph. Note that this operation can scrolls ten pixels for each pixel the mouse moves. Also, if OmniMoni is currently doing other things (updating widgets) when you try to do this the movement will be jerky. To restore position of the graph to the beginning, double click in the graph with the left mouse button.

Unpack Widget
    By clicking with the right mouse button on any widget it will remove that widget from the OmniMoni window. To restore the widget, you can use the Packing Menu (see below). Remember that some widgets are simply empty areas, so after unpacking all of the labels within these areas you will still need to unpack the empty area itself to fully unpack that group. If a group is unpacked then it will not be checked for updates. This can save system resources if there are items you do not need updated continuously. The only case where this is not true is for graphs. If an overall graph frame is unpacked that graph will still be updated (just out of sight). But, if the graph within the frame is unpacked, then the graph will stop being updated. Note that the only way to unpack the graph is from the Packing Menu.

Packing Menu
    By clicking the middle mouse button on any widget you will bring up a cascaded, hierarchical menu representing the structure of the current configuration. Each section (group or graph) will have a checkbutton next to it. If the checkbutton is marked, then that section is currently packed in the OmniMoni window. If you uncheck it, then it will be unpacked. Likewise, marking an unmarked checkbutton will repack the group. While in the menu, clicking the right mouse button will close the menu. For sections that contain other sections, the first checkbutton in their cascaded menu is "Frame". This represents that whole group and unmarking it will unpack the whole section and all subsections within it. For sections that contain other sections and have a label themselves, the second checkbutton will be the name of that section. This represents the label and unmarking it will unpack just the label to that group. For graphs, the checkbutton "Graph" will appear in the menu. This represents the graph itself (not the label for it and not the frame around it). Unchecking this will unpack just the graph. Doing this will stop the graph from being updated. Below the item "Graph" the items to be graphed will be listed. Unchecking any of them will remove it from the graph but will not stop it from being updated (it will simply not be shown). If a group is unpacked then it will not be checked for updates. This can save system resources if there are items you do not need updated continuously. The only case where this is not true is for graphs. If an overall graph frame is unpacked that graph will still be updated (just out of sight). But, if the graph within the frame is unpacked, then the graph will stop being updated.

Quitting
    While the mouse pointer is within the OmniMoni window, the widget does not matter, typing "Q" (capital "q") will cause OmniMoni to close all windows and exit.

Iconifying
    While the mouse pointer is within the OmniMoni window, typing "Z" (capital "z") will iconify OmniMoni. I chose "Z" because the operation is similar to suspension where the standard is control-z.

Changing Update Delta
    While the mouse pointer is within the OmniMoni window, typing the following characters will alter the update delta by the specified number of milliseconds:
    + = +1000    control + = +60,000
    - = -1000    control - = -60,000
    Changing the update delta will cause the next update to occur after the new number of milliseconds.

Changing the Debug Level
    While the mouse pointer is within the OmniMoni window, a number 1 through 6, will change the debug level. The level is altered by performing an xor on the current level with the the number 2 to the power of the number pressed minus one. Or, mathematically, if n is the number pressed:
        new_level = old_level ^ 2<<(n-1) Where the symbol "^" is xor and the symbol "<<" is left shift. For example, given the debug level starts at zero: typing 5 will make the new debug level 16, then typing 3 will make it 20, then typing 5 again will make it 4.

OMNIRC

Overview
    This section describes the format of the .omnirc file. This file tells OmniMoni what information to display, where to get that information, how to display it, and how often to update that information. In writing OmniMoni I constantly had to make decisions regarding the trade off of rc file simplicity and configurability. I hope that I have decided well, but if you have any suggestions or comments please email them to the address shown in the AUTHORS section.

Syntax
    The .omnirc file follows a relatively simple, recursive, format. The idea is that you have a command (there are currently four different possible commands) and somewhere in the command also have zero or more of the same command (i.e., at one recursive level lower). The commands currently recognized are configure, group, graph, and comment. It is important to note that each command (and all of its arguments) must be enclosed in curly braces, { and }. Also, the very first word (white space delimited) after the open brace is what specifies the command.

Variables
    Before any commands are looked at or evaluated a single pass through the configuration file is done to perform variable substitutions. A variable is in the form: $NAME. This is a dollar sign ($) followed by the variable name which must be only capital letters. If any variable is found in the configuration file, OmniMoni attempts to change it to a value that must have been specified on the command line (see the flag --set of the OPTIONS section). A variable can be ignored if the $ is preceeded by a backslash (\). This can allow you to have a word in the form of a variable without OmniMoni attempting to perform substitution. These variables can appear anywhere within the configuration file.

Configure
    There are global configuration options that will affect all of the following items in the configuration file. These global options can be overridden with later explicit configurations via the extras options, or via another configuration section. The format of the configure command is as follows: { configure [{ option value | wm command }]... }

    configure
        This is the keyword configure that designates this whole section (from the open brace preceding to the matching close brace at the end) as a configure command.

    option value
        This is the option which you want to configure, white space, and the the value to assign to it, the pair enclosed in curly braces. If either part of the pair requires spaces in it that part should be enclosed in the double quotes. OmniMoni currently recognizes two internal configuration options as well as all of the Tcl/Tk options for its option database. The internal options are:

        OMNIMONI_DELTA
            This designates the update time in milliseconds between checking for updates. The defaults is 1000, 1 second.

    wm command
        This is the keyword wm followed by any valid Tcl/Tk wm configuration command. The most likely command is probably "wm title . name". This allows you to change the title of the OmniMoni window to name.

Group
    The format of the group command is as follows: { group title {label} program update shape {extras} {[command]}... } Each piece of the above command is described below:

    group
        This is the keyword group that designates this whole section as a group command.

    title
        This is a text string without any white space or periods. This is the string that will be displayed in the menus.

    {label}
        This defines the text to be displayed, and possibly monitored. The format of a label is: { string shape {extras} } Where the different pieces are:

        string
            The string to be placed in the Tk widget. This can be plain text, in which case that text would be displayed, or it can include some special and mathematics symbols. These special symbols allow you to take certain pieces from the output of this group's parent's program. After discovering what these special symbols equate to OmniMoni will try to evaluate them and any mathematics symbols as a math expression. If this generates a number then that number will be the result of string. If this expression does not evaluate mathematically, then the exact characters in string will be used and displayed. The special symbols are:

            $n  This is a dollar sign, $, immediately followed by an integer number (multidigit is ok). This will return the field number n from the output of the parent's program. A field is a whitespace delimited word where the first field is field number 0. The fields progress horizontally, left to right, and vertically, up to down, the same way that English is read. If the number is less than 0 (the first field) or greater than the last field, then this will return a null string.

            %n  This is a percent sign, %, immediately followed by an integer number. The will return the same thing at $n except that it starts from the right and works left, and starts at the bottom and works up. If the number is less than 0 (the first field) or greater than the total last field, then this will return a null string.

            $n{symbol} or %n{symbol}
                This is a $n or %n symbol followed by another special symbol enclosed in curly braces, {}. This will evaluate the $n or %n and retrieve that information. It will then recursively evaluate symbol on that information. This will work if the original output contain pieces enclosed in curly braces or in double quotes. This can easily be accomplished by piping the original command through awk and printing the needed braces or quotes.

            $s or %s
                This is a dollar sign, $, or percent sign, %, immediately followed by the letter s. Both symbols return the same information. This returns the number of seconds since this label was last updated. This can be useful if you are trying to calculate the number of foos per second and the output from program only returns the total. See the next special symbol as well for doing this.

            =<$n|%n>
                This is an equals sign, =, immediately followed by either a $n or %n symbol. This returns the value from field n from the previous output from program (i.e., the previous time program generated output). This allows you to compute the difference between two updates. Note that if you use this symbol the widget will show the exact characters in string until a second update has occurred so that there is a previous set of output to evaluate.

            :<$n1|$n1><$n2|$n2>
                This is a colon, :, immediately followed by two $n or %n symbols (they do not need to be the same symbol); the angle brackets are not included. This returns the range of values from field n1 to n2 (including both end fields). The $ and % symbols follow the constructs as described above. This can be useful if program returns a lot of output that you want to use as is. A simple example is, :$0%0, which returns every field from the output.

            |c  This is a pipe (also known as a logical or), |, immediately followed by one single character. This will return nothing, but it will split the output from program into extra fields at each character c. For future symbols in this string, words will still be delimited by white space except that this replaces each character c with whitespace.

        shape
            The shape or placement for this label (in relation to following widgets). See the main shape description below for details.

        {extras}
            Extra configuration items for this label. See the main extras description below for details.

    program
        This is a shell program or command that produces the output from which you want to take information. This can be a compound statement; that is it can include multiple commands (separated with semicolons, ";") and can include pipes, redirections, etc. If there is any whitespace in the complete command then it must be enclosed in double quotes (this will almost always be the case).

    update
        This is the time in seconds which this group's groups are reparsed (and possibly updated). It is important to realize two things regarding this number. One: it affects any groups that are within this one. So, this update time must be less than or equal to the smallest update time of all lower items. Two: This number does not affect the update time for this item's label. This item's parent's update time would specify that.

    shape
        This is the side which each item within this one is placed on the screen. As with update this affects all lower items, not this one. Possible shapes are: top, bottom, left, and right.

    {extras}
        This specifies any extra Tk configuration items. They are parsed as a pair (e.g., "-background red"). Each pair should be enclosed in quotes due to the whitespace between them. Any number of extra options are allowed with each quoted pair being separated by whitespace. For a complete description of the possible options see the Tcl/Tk man page options.

    [{command}]...
        This is zero or more additional configuration file commands (configure, group, graph, or comment). Each one must be enclosed in curly braces and they must be separated by whitespace. If there are none you must still have the empty set of braces, {}.

Graph
    The graph command allows you to graph numerical date in one of two ways, solid or lined. These two ways may be mixed on a single graph. If they are then all solid items are behind the hash marks and all lined items are in front of the hash marks. These graphs will correctly graph negative values, this allows you to "flip" a graph by making all of the values negative. The format of the graph command is as follows: { graph title {label} program width height hash zero-color hash-color update direction history extras [{line}]... } Each piece of the above command is described below:

    graph
        This is the keyword graph that designates this whole section as a graph command.

    title
        This is a text string without any white space of periods. This is the string that will be displayed in the menus.

    {label}
        This defines the text to be displayed, and possibly monitored. The format of Ilabel is the same as that for group above.

    program
        This is a shell program or command that produces the output from which you want to take information. This can be a compound statement; that is it can include multiple commands (separated with semicolons, ";") and can include pipes, redirections, etc. If there is any whitespace in the complete command then it must be enclosed in double quotes.

    width
        This is the width, in pixels, of this graph.

    height
        This is the height, in pixels, of this graph.

    hash
        This is the value at which you want hash marks displayed. The unit for this value should be in reference to the output you expect to receive.

    zero-color
        This is the color for the hash mark at zero. If this is a null string, "", then the color will be clear and this will not show.

    hash-color
        This is the color for all non-zero hash marks. If this is a null string, "", then the color will be clear and this will not show.

    update
        This is the time in seconds which this graph is updated.

    direction
        This is the direction this graph will scroll as more lines are added. Possible values are: "up", "down", "left", or "right". Note that opposite directions are mirror images of each other, not rotated. To get a rotated effect you can make all values being graphed the opposite sign (i.e., negative to positive and positive to negative), and then use the opposite direction.

    history
        This is the value in pixels (and number of updates) which will be remembered. After part of the graph has scrolled out of view of the graph, you can use the mouse to scroll back and see it (see the Scrolling Graphs subsection of the USAGE section above).

    extras
        This specifies any extra Tk configuration items. They are parsed as a pair (e.g., "-background red"). Each pair should be enclosed in quotes due to the whitespace between them. Any number of extra options are allowed with each quoted pair being separated by whitespace. For a complete description of the possible options see the Tcl/Tk man page options.

    [{line}]...
        This is zero or more items describing what lines to graph. The format of line is as follows: { title label color type } Each piece of the above is described below:

        title
            This is a text string without any whitespace of periods. This is the string that will be displayed in the menus.

        label
            This defines the text to be displayed, and possibly monitored. The format of Ilabel is the same as that for group above.

        color
            This is the color of this line to be graphed.

        type
            This is the type or style of this piece to be graphed. The possible types are: solid or lined. The method in which the solid graph handles layers is somewhat unusual. The idea is that the higher the absolute value of the value being graphed, the further "behind" other values it is graphed. This insures that at least part of all items can be seen, unless two items have the same value. This is done on a per update basis. Therefore, as items change position the graph may take on a striped appearance. This is intentional.

Comment
    The format of the comment command is as follows: { comment ... } This is simply the keyword comment (or the character "#") followed by whitespace followed by anything. Everything after the keyword is ignored up until the matching close brace. This does mean, however, that extraneous curly braces (even in a comment) can cause errors. It is safe to have matching curly braces in a comment, or to precede them with backslashes (\{ or \fR), but it is even safer to not use any curly braces in a comment.

FILES

~/.omnirc
    The default configuration file.

LEGAL
OmniMoni, Copyright (C) 1995 Rainer Mager 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. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

AUTHORS
Rainer Mager - email bug reports, questions, comments to rvm@fore.com.