view release on metacpan or  search on metacpan

pod/afsmonitor.pod  view on Meta::CPAN

#------------------------------------------------------------------------------
# afsmonitor.pod
#
# Copyright © 2004-2006 Alf Wachsmann <alfw@slac.stanford.edu> and
#                  Elizabeth Cassell <e_a_c@mailsnare.net>
#
# $Revision: 1.12 $ $Date: 2006/07/05 22:25:10 $ $Author: alfw $
#
# This library is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.
#------------------------------------------------------------------------------

=head1 NAME

B<afsmonitor> - Gathers statistics about File Servers and Cache Managers

=head1 SYNOPSIS

  use AFS::Monitor;
  my ($fs, $cm);

  ($fs, $cm) = afsmonitor(cmhosts => "hostName1");

  ($fs, $cm) = afsmonitor(
                          cmhosts => ["hostName1", "hostName2"],
                          fshosts => ["hostName3", "hostName4"],
                         );

  ($fs, $cm) = afsmonitor(
                          config => "configfilename",
                          output => "outputfilename",
                          detailed => 1,
                         );

  foreach $host (@$fs) {
    print "FS Host: $host->{hostName}\n";
    if($host->{probeOK}) {
      print "probe successful\n";
    }
    else {
      print "probe failed\n";
    }
  }

  ($fs, $cm) =
    afsmonitor(
           cmhosts  => ["hostName1", "hostName2"],
           fshosts  => ["hostName3", "hostName4", "hostName5"],
           cmshow   => ["PerfStats_section", "fs_oc_downDst_more_50"],
           fsshow   => ["VnodeCache_group", "FetchData_sqr"],
           fsthresh => [
                        { vcache_S_Entries => 10
                        },
                        { vcache_L_Allocs  => 30
                        },
                        { host => "hostName3",
                          vcache_L_Writes => 20,
                          handler => "HandlerScript arg1 arg2"
                        },
                        { host => "hostName5",
                          vcache_L_Writes => 40,
                        }
                       ],
           cmthresh => [
                        { host => "hostName1",
                          numPerfCalls => 80,
                          handler => "HandlerScript arg"
                        },
                        { fs_oc_downDst_more_50 => 90
                        },
                        { cacheNumEntries => 60,
                          handler => "HandlerScript"
                        },
                        { host => "hostName2",
                          dlocalAccesses => 70
                        }
                       ],
           );

=head1 DESCRIPTION

The B<afsmonitor> function gathers statistics about specified File Server
and Cache Manager operations. It allows the issuer to monitor, from a
single location, a wide range of File Server and Cache Manager
operations on any number of machines in both local and foreign cells.

There are 271 available File Server statistics and 571 available Cache
Manager statistics, listed in the L<afsmon_stats(1)> documentation. By default,
the command displays all of the relevant statistics for the file server
machines named by the B<fshosts> argument and the client machines named
by the B<cmhosts> argument. To limit the display to only the statistics
of interest, list them in the configuration file specified by the
B<config> argument. In addition, use the configuration file for the
following purposes:

=over

=item *

To set threshold values for any statistic. The statistics with values exceeding
their thresholds are indicated in the returned data structure. There are no

pod/afsmonitor.pod  view on Meta::CPAN

=head1 OUTPUT

The return values are references to two arrays, one for file
servers and one for cache managers. Each entry in each array
is a reference to a hash containing information about one of
the hosts specified either by the fshosts or cmhosts options,
or in the config file. Each hash in these arrays contains the
following entries:

=over

=item B<hostName>

The name of the host that these statistics represent.

=item B<probeOK>

1 if the statistics were gathered successfully, 0 if the probe failed and no statistics were gathered.

=item B<section_names>

The rest of the keys are the names of sections of statistics (specified in the
L<afsmon_stats(1)> documentation).
Each section entry points to another hash containing entries for each group of
statistics (with keys corresponding to the group name) within that section.
Each group entry points to another hash containing entries for all of the
individual statistics (with keys corresponding to the name of the statistic)
within that group.
The individual statistics also point to hashes, containing up to three entries:

=over

=item B<value>

The value of the statistic for this host.

=item B<overflow>

This key will be present if the value has exceeded a threshold provided in the configuration file.
If a command to execute was specified for this threshold, this entry will contain a string with
the name of the command and all of the parameters that should be passed to the command.
If no command to execute was specified, the value of this entry will be 1.

=item B<threshold>

If this value has exceeded a threshold, this entry will contain the threshold value.
The threshold key will not exist in the hash if no threshold was specified, or if the
specified threshold was not exceeded.

=back

If a config file with "show" directives was given, then only the statistics specified
in the config file will be included, and any groups or sections that were not specified
by a "show" statement and in which no individual statistics were specified by a "show"
statement will not be included.

=back

For examples of accessing the information in the returned data structures
and printing it in a readable format, refer to the B<afsmonitor> script
in the B<examples> directory.

=head1 WRITING TO AN OUTPUT FILE

Include the B<output> argument to name the file into which the
B<afsmonitor> function writes all of the statistics it collects.

The output file is in ASCII format and records the same
information as is returned in the File Server and Cache Manager
data structures. The output file has the following format:

   time  host_name  CM|FS   list_of_measured_values

and specifies the time at which the list_of_measured_values were
gathered from the Cache Manager (CM) or File Server (FS) process
housed on host_name. On those occasion where probes fail, the
value -1 is reported instead of the list_of_measured_values.

If the administrator usually reviews the output file manually,
rather than using it as input to an automated analysis program or
script, including the B<detail> flag formats the data in a more
easily readable form.

=head1 THE CONFIGURATION FILE

To customize the B<afsmonitor> function, create an ASCII-format
configuration file and use the B<config> argument to name it. You
can specify the following in the configuration file:

=over

=item *

The File Servers, Cache Managers, or both, to gather statistics on.

=item *

The statistics to display. By default, the display includes 271
statistics for File Servers and 571 statistics for Cache Managers.
For information on the available statistics, see the L<afsmon_stats(1)>
documentation.

=item *

The threshold values to set for statistics and a script or program
to associate with the statistic if a threshold is exceeded. By
default, no threshold values are defined.

=back

The following list describes the instructions that can appear
in the configuration file:

=over

=item B<cm I<host_name>>

Names a client machine for which to display statistics.

=item B<fs I<host_name>>