PGGT : Performance Gathering & Graphing Tools

What is PGGT?
=============

    As a sysadmin, I always thought it odd that nobody had written
    and released (or I could never find) tools to allow for gathering
    and graphing iostat, vmstat, and netstat data.  It seems like such
    a basic performance troubleshooting thing to do, yet is cumbersome
    to deal with unless you like paging through multi-megabyte log files.

    PGGT is a set of tools for gathering and graphing the information
    collected by the *stat suite of commands:  iostat, vmstat, netstat

    PGGT's pieces and methodology are described below.  It is highly
    recommended that you invest the time necessary to read this entire
    file if you are seriously considering this set of tools.

    If you are interested in downloading PGGT, you should see the project
    page at SourceForge.

Requirements
============

    1.  UNIX (Tested only under Solaris so far, but very likely to work
        elsewhere)

    2.  For the use of anything other than 'statter' mentioned below,
        Python 2.0 or higher is needed.

    3.  If you intend to do graphing, you also need the 'Biggles' Python
        module and its requirements (currently GNU libplot and the Numeric
        Python module).  See http://biggles.sf.net/

Data Gathering
==============

    A single script 'statter' allows one to specify the *stat
    command to use, where to log the data, and how often to collect
    a sample.

    Example: statter -l /proj1/logs -c 'iostat -xnp' -i 5 -b 7 -e 18

    Meaning: Between 7:00 and 18:00, gather the output of 'iostat -xnp'
             every 5 seconds and log the results to the directory /proj1/logs

    For more information, see 'statter -h'

SLF: Stat Log Format (Processing and Graphing)
==============================================

    The outputs of the iostat, vmstat, and netstat commands have nothing
    in common with each other and none of the lines are timestamped (which
    is necessary for graphing data across a time period).

    SLF (Stat Log Format) is a "common ground" file format.  It's nothing
    special or complex:

        1.  Lines beginning with the comment character '#' are ignored.

        2.  Every non-comment line is a data line.  There are no headers
            for the columns.

        3.  Column 0 of every data line contains a timestamp integer
            representing seconds since the beginning of the UNIX epoch.

    The '*2slf*' scripts take raw statter-produced output and produce
    SLF log files which are suitable for feeding to slf2gif.

Miscellaneous Notes
===================

    - The included 'loadstat' script adds to your arsenal of stat-gathering
      commands.  More information about it can be found in the comments at
      the top of the script.

    - Please read the file 'TODO-BUGS-ERRATA'

COPYRIGHT
=========

    (c) 2002 The MITRE Corporation.  All rights reserved.

OPTIONAL Reading
================

    Script Logic (statter)
    ----------------------

        process arguments
        perform pre-start checks (permissions on logdir, etc)
        while forever
            determine current_hour
            if current_hour >= begin_hour
                if current_hour <= end_hour
                    # We're in our window of execution
                    if command is running:
                        # Good
                        sleep 2 minutes
                    else
                        write starting timestamp and interval to log file
                        start command
                else
                    kill off any running command and don't gather 
            else
                sleep 2 minutes

    Script Logic (slf2gif)
    ----------------------

        # Reminder: Fill this in at some point :)