Provided by: libsys-statistics-linux-perl_0.66-1_all bug

NAME

       Sys::Statistics::Linux - Front-end module to collect system statistics

SYNOPSIS

           use Sys::Statistics::Linux;

           my $lxs = Sys::Statistics::Linux->new(
               sysinfo   => 1,
               cpustats  => 1,
               procstats => 1,
               memstats  => 1,
               pgswstats => 1,
               netstats  => 1,
               sockstats => 1,
               diskstats => 1,
               diskusage => 1,
               loadavg   => 1,
               filestats => 1,
               processes => 1,
           );

           sleep 1;
           my $stat = $lxs->get;

DESCRIPTION

       Sys::Statistics::Linux is a front-end module and gather different linux system information
       like processor workload, memory usage, network and disk statistics and a lot more. Refer
       the documentation of the distribution modules to get more information about all possible
       statistics.

MOTIVATION

       My motivation is very simple... every linux administrator knows the well-known tool sar of
       sysstat.  It helps me a lot of time to search for system bottlenecks and to solve
       problems, but it's hard to parse the output if you want to store the statistics into a
       database. So I thought to develope Sys::Statistics::Linux. It's not a replacement but it
       should make it simpler to you to write your own system monitor.

       If Sys::Statistics::Linux doesn't provide statistics that are strongly needed then let me
       know it.

TECHNICAL NOTE

       This distribution collects statistics by the virtual /proc filesystem (procfs) and is
       developed on the default vanilla kernel. It is tested on x86 hardware with the
       distributions RHEL, Fedora, Debian, Ubuntu, Asianux, Slackware, Mandriva and openSuSE
       (SLES on zSeries as well but a long time ago) on kernel versions 2.4 and/or 2.6. It's
       possible that it doesn't run on all linux distributions if some procfs features are
       deactivated or too much modified.  As example the linux kernel 2.4 can compiled with the
       option "CONFIG_BLK_STATS" what turn on or off block statistics for devices.

       Don't give up if some of the modules doesn't run on your hardware! Tell me what's wrong
       and I will try to solve it! You just have to make the first move and to send me a mail.
       :-)

VIRTUAL MACHINES

       Note that if you try to install or run "Sys::Statistics::Linux" under virtual machines on
       guest systems that some statistics are not available, such as "SockStats", "PgSwStats" and
       "DiskStats". The reason is that not all /proc data are passed to the guests.

       If the installation fails then try to force the installation with

           cpan> force install Sys::Statistics::Linux

       and notice which tests fails, because this statistics maybe not available on the virtual
       machine - sorry.

DELTAS

       The statistics for "CpuStats", "ProcStats", "PgSwStats", "NetStats", "DiskStats" and
       "Processes" are deltas, for this reason it's necessary to initialize the statistics before
       the data can be prepared by "get()". These statistics can be initialized with the methods
       "new()", "set()" and "init()". For any option that is set to 1, the statistics will be
       initialized by the call of "new()" or "set()". The call of init() re-initialize all
       statistics that are set to 1 or 2.  By the call of "get()" the initial statistics will be
       updated automatically. Please refer the section "METHODS" to get more information about
       the usage of "new()", "set()", "init()" and "get()".

       Another exigence is to sleep for a while - at least for one second - before the call of
       "get()" if you want to get useful statistics. The statistics for "SysInfo", "MemStats",
       "SockStats", "DiskUsage", "LoadAVG" and "FileStats" are no deltas. If you need only one of
       these information you don't need to sleep before the call of "get()".

       The method "get()" prepares all requested statistics and returns the statistics as a
       Sys::Statistics::Linux::Compilation object. The inital statistics will be updated.

MANUAL PROC(5)

       The Linux Programmer's Manual

           http://www.kernel.org/doc/man-pages/online/pages/man5/proc.5.html

       If you have questions or don't understand the sense of some statistics then take a look
       into this awesome documentation.

OPTIONS

       All options are identical with the package names of the distribution in lowercase. To
       activate the gathering of statistics you have to set the options by the call of "new()" or
       "set()".  In addition you can deactivate statistics with "set()".

       The options must be set with one of the following values:

           0 - deactivate statistics
           1 - activate and init statistics
           2 - activate statistics but don't init

       In addition it's possible to pass a hash reference with options.

           my $lxs = Sys::Statistics::Linux->new(
               processes => {
                   init => 1,
                   pids => [ 1, 2, 3 ]
               },
               netstats => {
                   init => 1,
                   initfile => $file,
               },
           );

       Option "initfile" is useful if you want to store initial statistics on the filesystem.

           my $lxs = Sys::Statistics::Linux->new(
               cpustats => {
                   init     => 1,
                   initfile => '/tmp/cpustats.yml',
               },
               diskstats => {
                   init     => 1,
                   initfile => '/tmp/diskstats.yml',
               },
               netstats => {
                   init     => 1,
                   initfile => '/tmp/netstats.yml',
               },
               pgswstats => {
                   init     => 1,
                   initfile => '/tmp/pgswstats.yml',
               },
               procstats => {
                   init     => 1,
                   initfile => '/tmp/procstats.yml',
               },
           );

       Example:

           #!/usr/bin/perl
           use strict;
           use warnings;
           use Sys::Statistics::Linux;

           my $lxs = Sys::Statistics::Linux->new(
               pgswstats => {
                   init => 1,
                   initfile => '/tmp/pgswstats.yml'
               }
           );

           $lxs->get(); # without to sleep

       The initial statistics are stored to the temporary file:

           #> cat /tmp/pgswstats.yml
           ---
           pgfault: 397040955
           pgmajfault: 4611
           pgpgin: 21531693
           pgpgout: 49511043
           pswpin: 8
           pswpout: 272
           time: 1236783534.9328

       Every time you call the script the initial statistics are loaded/stored from/to the file.
       This could be helpful if you doesn't run it as daemon and if you want to calculate the
       average load of your system since the last call. Do you understand? I hope so :)

       To get more information about the statistics refer the different modules of the
       distribution.

           sysinfo     -  Collect system information              with Sys::Statistics::Linux::SysInfo.
           cpustats    -  Collect cpu statistics                  with Sys::Statistics::Linux::CpuStats.
           procstats   -  Collect process statistics              with Sys::Statistics::Linux::ProcStats.
           memstats    -  Collect memory statistics               with Sys::Statistics::Linux::MemStats.
           pgswstats   -  Collect paging and swapping statistics  with Sys::Statistics::Linux::PgSwStats.
           netstats    -  Collect net statistics                  with Sys::Statistics::Linux::NetStats.
           sockstats   -  Collect socket statistics               with Sys::Statistics::Linux::SockStats.
           diskstats   -  Collect disk statistics                 with Sys::Statistics::Linux::DiskStats.
           diskusage   -  Collect the disk usage                  with Sys::Statistics::Linux::DiskUsage.
           loadavg     -  Collect the load average                with Sys::Statistics::Linux::LoadAVG.
           filestats   -  Collect inode statistics                with Sys::Statistics::Linux::FileStats.
           processes   -  Collect process statistics              with Sys::Statistics::Linux::Processes.

METHODS

   new()
       Call "new()" to create a new Sys::Statistics::Linux object. You can call "new()" with
       options.  This options would be passed to the method "set()".

       Without options

           my $lxs = Sys::Statistics::Linux->new();

       Or with options

           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );

       Would do nothing

           my $lxs = Sys::Statistics::Linux->new( cpustats => 0 );

       It's possible to call "new()" with a hash reference of options.

           my %options = (
               cpustats => 1,
               memstats => 1
           );

           my $lxs = Sys::Statistics::Linux->new(\%options);

   set()
       Call "set()" to activate or deactivate options.

       The following example would call "new()" and initialize "Sys::Statistics::Linux::CpuStats"
       and delete the object of "Sys::Statistics::Linux::SysInfo".

           $lxs->set(
               processes =>  0, # deactivate this statistic
               pgswstats =>  1, # activate the statistic and calls new() and init() if necessary
               netstats  =>  2, # activate the statistic and call new() if necessary but not init()
           );

       It's possible to call "set()" with a hash reference of options.

           my %options = (
               cpustats => 2,
               memstats => 2
           );

           $lxs->set(\%options);

   get()
       Call "get()" to get the collected statistics. "get()" returns a
       Sys::Statistics::Linux::Compilation object.

           my $lxs  = Sys::Statistics::Linux->new(\%options);
           sleep(1);
           my $stat = $lxs->get();

       Or you can pass the time to sleep with the call of "get()".

           my $stat = $lxs->get($time_to_sleep);

       Now the statistcs are available with

           $stat->cpustats

           # or

           $stat->{cpustats}

       Take a look to the documentation of Sys::Statistics::Linux::Compilation for more
       information.

   init()
       The call of "init()" initiate all activated statistics that are necessary for deltas. That
       could be helpful if your script runs in a endless loop with a high sleep interval. Don't
       forget that if you call "get()" that the statistics are deltas since the last time they
       were initiated.

       The following example would calculate average statistics for 30 minutes:

           # initiate cpustats
           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );

           while ( 1 ) {
               sleep(1800);
               my $stat = $lxs->get;
           }

       If you just want a current snapshot of the system each 30 minutes and not the average then
       the following example would be better for you:

           # do not initiate cpustats
           my $lxs = Sys::Statistics::Linux->new( cpustats => 2 );

           while ( 1 ) {
               $lxs->init;              # init the statistics
               my $stat = $lxs->get(1); # get the statistics
               sleep(1800);             # sleep until the next run
           }

       If you want to write a simple command line utility that prints the current workload to the
       screen then you can use something like this:

           my @order = qw(user system iowait idle nice irq softirq total);
           printf "%-20s%8s%8s%8s%8s%8s%8s%8s%8s\n", 'time', @order;

           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );

           while ( 1 ){
               my $cpu  = $lxs->get(1)->cpustats;
               my $time = $lxs->gettime;
               printf "%-20s%8s%8s%8s%8s%8s%8s%8s%8s\n",
                   $time, @{$cpu->{cpu}}{@order};
           }

   settime()
       Call "settime()" to define a POSIX formatted time stamp, generated with localtime().

           $lxs->settime('%Y/%m/%d %H:%M:%S');

       To get more information about the formats take a look at "strftime()" of POSIX.pm or the
       manpage strftime(3).

   gettime()
       "gettime()" returns a POSIX formatted time stamp, @foo in list and $bar in scalar context.
       If the time format isn't set then the default format "%Y-%m-%d %H:%M:%S" will be set
       automatically. You can also set a time format with "gettime()".

           my $date_time = $lxs->gettime;

       Or

           my ($date, $time) = $lxs->gettime();

       Or

           my ($date, $time) = $lxs->gettime('%Y/%m/%d %H:%M:%S');

EXAMPLES

       A very simple perl script could looks like this:

           use strict;
           use warnings;
           use Sys::Statistics::Linux;

           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
           sleep(1);
           my $stat = $lxs->get;
           my $cpu  = $stat->cpustats->{cpu};

           print "Statistics for CpuStats (all)\n";
           print "  user      $cpu->{user}\n";
           print "  nice      $cpu->{nice}\n";
           print "  system    $cpu->{system}\n";
           print "  idle      $cpu->{idle}\n";
           print "  ioWait    $cpu->{iowait}\n";
           print "  total     $cpu->{total}\n";

       Set and get a time stamp:

           use strict;
           use warnings;
           use Sys::Statistics::Linux;

           my $lxs = Sys::Statistics::Linux->new();
           $lxs->settime('%Y/%m/%d %H:%M:%S');
           print $lxs->gettime, "\n";

       If you want to know how the data structure looks like you can use "Data::Dumper" to check
       it:

           use strict;
           use warnings;
           use Sys::Statistics::Linux;
           use Data::Dumper;

           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
           sleep(1);
           my $stat = $lxs->get;

           print Dumper($stat);

       How to get the top 5 processes with the highest cpu workload:

           use strict;
           use warnings;
           use Sys::Statistics::Linux;

           my $lxs = Sys::Statistics::Linux->new( processes => 1 );
           sleep(1);
           my $stat = $lxs->get;
           my @top5 = $stat->pstop( ttime => 5 );

BACKWARD COMPATIBILITY

       The old options and keys - CpuStats, NetStats, etc - are still available but deprecated!
       It's not possible to access the statistics via Sys::Statistics::Linux::Compilation and
       it's not possible to call "search()" and "psfind()" if you use the old options.

       You should use the new options and access the statistics over the accessors

           $stats->cpustats

       or directly with

           $stats->{cpustats}

PREREQUISITES

           Carp
           POSIX
           Test::More
           Time::HiRes
           UNIVERSAL

EXPORTS

       No exports.

TODOS

          * Are there any wishs from your side? Send me a mail!

REPORTING BUGS

       Please report all bugs to <jschulz.cpan(at)bloonix.de>.

AUTHOR

       Jonny Schulz <jschulz.cpan(at)bloonix.de>.

COPYRIGHT

       Copyright (C) 2006-2008 by Jonny Schulz. All rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.