Alan Burlison

NAME

StatsView - Solaris performance data collection and graphing package

SYNOPSIS

   use StatsView::Graph;
   my $graph = StatsView::Graph->new("sar.txt");
   $graph->read("CPU usage");
   $graph->define(columns => [ "%idle" ]);
   $graph->save(file => "sar_idle_cpu.gif", format => "gif");

DESCRIPTION

StatsView::Graph is a package that was originally written for internal use within the Sun UK Performance Centre. It allows the display of the output of the standard Solaris utilities sar, iostat, mpstat and vmstat, as well as the output of vxstat if Veritas Volume Manager is in use. It also supports the iost+ utility (available as part of the CPAN Solaris::Kstat package), and the output of the Oracle monitoring provided by the sv script. The sv script is merely a GUI front-end around this pakage.

PREREQUISITES

This package requires gnuplot, at least version beta 340. If you wish to produce GIF plots you will also need a gnuplot that is built with support for the GD GIF library.

TERMINOLOGY

 category   - A class of related data, for applications that
              collect more than one type of data at a time
              eg for sar, CPU utilisation, Disk IO etc
 column     - A time-series of data, eg %busy 
 instance   - An entity for which data is collected
              eg disk drive, Oracle tablespace
 sample     - All data collected at a given point in time
 data point - An individual statistic value
              eg reads/sec for disk c0t0d0 at 10:35:04

Data of 2 types can be displayed by StatsView - 2d or 3d. 2d data does not have any instance information, eg for CPU usage, total idle, usr, sys, wio. 3d data has instance information, eg for Disk usage, reads/sec, writes/sec by disk.

METHODS

new()

This takes a single argument, the name of a statistics file to open. This can be the output of one of the following commands:

   iost+                      - see the Solaris::Kstats module
   iostat -x                  - extended device statistics format
   Built-in Oracle monitoring - collected via sv
   sar                        - binary or text format
   vmstat                     - standard format
   mpstat                     - standard format
   vxstat                     - Veritas VM statistics

Note that iostat, mpstat and vmstat don't put timestamps in their output, thus making it impossible to decide hown the data should be graphed. To circumvent this problem it is necessary to add a header line to the start of the data files of the form:

   Start: 01/01/1998 12:00:00 Interval: 10

Giving the start of the sampling period in dd/mm/yyyy hh:mm:ss format and the interval between samples in seconds. This is done automatically if the data is collected via the sv script.

read()

This reads in the data from the file. For data files that contain more than one category of data, the name of the category to read should be given as an argument, eg for sar "CPU usage" or "Disk IO". The get_categories() method can be used to find out all the available categories - see below.

define()

This defines the parameters of the graph that is to be drawn. It takes a list of key-value parameter pairs. Different parameters are supported depending on whether the data is 2d or 3d. Parameters allowed for both 2d and 3d data are:

   scale => "normal" | "logarithmic"

The default is "normal".

For 2d data the expected parameter is:

   columns => [ <list of columns to plot> ]

For 3d data the expected parameters are:

   column    => <column name>
   instances => [ <list of instances to plot> ]

The available columns and instances can be retrieved via the get_columns() and get_instances() methods - see below.

plot()

This takes no arguments, and plots the currently defined graph to the screen.

print()

This prints the currently defined graph. It takes a list of key-value parameter pairs. Allowed parameters are:

   orientation => "landscape" | "portrait"   default: landscape
   color       => "monochrome" | "color"     default: color
   printer     => <printer command>          Eg "lp", "lp -d myprinter"
   type        => "postscript" | "laserjet ii" | "laserjet iii"

save()

This saves the currently defined graph to a file. It takes a list of key-value parameter pairs. Allowed parameters are:

   orientation => "landscape" | "portrait"   default: landscape
   color       => "monochrome" | "color"     default: color
   file        => <output filename>
   format      => "csv"          comma-separated text
                | "postscript"   postscript format
                | "cgm"          Computer Graphics Metafile
                                 - For M$ Word, etc
                | "mif"          Framemaker
                | "gif"          requires gnuplot built with GD support

get_data_type()

This returns the type of the data in the file - either "2d" or "3d" (see TERMINOLOGY above). For data files that contain more than obe category of data, the name of a catogory should be supplied as an argument.

get_columns()

This returns a list of the available columns.

get_instances()

This returns a list of the available instances, for 3d data. For 2d data it will return an empty list.

get_times()

This returns a 3 element list of (start time, sampling interval, end time). Start and end time are expressed as a standard Unix 32-bit time value, and the sampling interval is expressed in seconds.

get_title()

This returns the title that will be displayed at the top of the graph.

get_categories()

This will return a list of all the available categories, for files that contain several categories of data. For files that only contain 1 category of data it will return an empty list.

get_file()

This returns the name of the data file that has been read in.

AUTHOR

Support questions and suggestions can be directed to Alan.Burlison@uk.sun.com

COPYRIGHT AND DISCLAIMER

Copyright (c) 1998 Alan Burlison

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file, with the exception that it cannot be placed on a CD-ROM or similar media for commercial distribution without the prior approval of the author.

This code is provided with no warranty of any kind, and is used entirely at your own risk.

This code was written by the author as a private individual, and is in no way endorsed or warrantied by Sun Microsystems.