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

SYNOPSIS
       use Sys::Statistics::Linux;

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

       $lxs->set(
          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 the front-end module to Sys-Statistics-Linux
    and collects different linux system informations like processor
    workload, memory usage, network and disk statistics and a lot more.
    Refer the documentation of the distribution modules to get more
    informations 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 to store different statistics into a database. So I though to
    develope this module. 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.

    If you need some statistics that aren't provided by Sys-Statistics-Linux
    but strongly needed then let me know it.

TECHNICAL NOTE
    This distribution collects statistics by the virtual /proc filesystem
    (procfs) and is developed on default vanilla kernels. It is tested on
    x86 hardware with the distributions SuSE (SuSE on s390 and s390x
    architecture as well), openSUSE, RHLE, Fedora, Debian, Ubuntu, Asianux,
    Slackware and Mandriva on kernel versions 2.4 and/or 2.6 and should run
    on all linux kernels with a default vanilla kernel as well. It's
    possible that it doesn't run on all linux distributions if some procfs
    features are deactived 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.

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

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

    The method "get()" then prepares all requested statistics and returns it
    as a hash reference. The inital statistics will be updated. You can turn
    on and off options with "set()".

OPTIONS
    All options are identical with the package names of the distribution. To
    activate the gathering of statistics you have to set the options by the
    call of "new()" or "set()". In addition you can delete, set pause or
    create new statistics with "set()" and re-init all statistics with
    "init()".

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

        0 - deactivate statistics
        1 - create a new object and init statistics if necessary
        2 - create a new object if not exists but wouldn't init statistics

    In addition it's possible to handoff a process list for option
    "Processes".

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

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

       SysInfo     -  Collect system informations             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 handoff 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);

    Take a look to "set()" for more informations.

  set()
    Call "set()" to activate or deactivate options. The following example
    would call "new()" and "init()" of "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 the
    statistics as a hash reference.

             my $stats = $lxs->get;

  init()
    The call of "init()" re-init all statistics that are necessary for
    deltas and if the option is higher than 0.

             $lxs->init;

  search(), psfind()
    Both methods provides a simple scan engine to find special statistics.
    Both methods except a filter as a hash reference as the first argument.
    If your data comes from extern - maybe from a client that send his
    statistics to the server - you can set the statistics as the second
    argument. The second argument have to be a hash reference as well.

    The method "search()" scans for statistics and rebuilds the hash tree
    until that keys that matched your filter and returns the hits as a hash
    reference.

            my $hits = $lxs->search({
               Processes => {
                  cmd   => qr/\[su\]/,
                  owner => qr/root/
               },
               CpuStats => {
                  idle   => 'lt:10',
                  iowait => 'gt:10'
               },
               DiskUsage => {
                  '/dev/sda1' => {
                     usageper => 'gt:80'
                  }
               }
            });

    This would return the following matches:

        * processes with the command "[su]"
        * processes with the owner "root"
        * all cpu where "idle" is less than 50
        * all cpu where "iowait" is grather than 10
        * only disk '/dev/sda1' if "usageper" is grather than 80

    If the statistics are not gathered by the current process then you can
    handoff statistics as an argument.

            my %stats = (
               CpuStats => {
                  cpu => {
                     system => '51.00',
                     total  => '51.00',
                     idle   => '49.00',
                     nice   => '0.00',
                     user   => '0.00',
                     iowait => '0.00'
                  }
               }
            );
               
            my %filter = (
               CpuStats => {
                  total => 'gt:50'
               }
            );

            my $hits = $lxs->search(\%filter, \%stats);

    The method "psfind()" scans for processes only and returns a array
    reference with all process IDs that matched the filter. Example:

            my $pids = $lxs->psfind({ cmd => qr/init/, owner => 'eq:apache' });

    You can handoff the statistics as second argument as well.

            my $pids = $lxs->psfind(\%filter, \%stats);

    This would return the following process ids:

        * processes that matched the command "init"
        * processes with the owner "apache"

    There are different match operators available:

        gt  -  grather than
        lt  -  less than
        eq  -  is equal
        ne  -  is not equal

    Notation examples:

        gt:50
        lt:50
        eq:50
        ne:50

    Both argumnents have to be set as a hash reference.

    Note: the operators < > = ! are not available any more. It's possible
    that in further releases could be different changes for "search()" and
    "psfind()". So please take a look to the documentation if you use it.

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

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

    To get more informations 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 warnings;
             use strict;
             use Sys::Statistics::Linux;

             my $lxs = Sys::Statistics::Linux->new( CpuStats => 1 );
             sleep(1);
             my $stats = $lxs->get;
             my $cpu   = $stats->{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 warnings;
             use strict;
             use Sys::Statistics::Linux;

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

    If you're not sure you can use the the "Data::Dumper" module to learn
    more about the hash structure:

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

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

             print Dumper($stats);

    How to get processes with the highest cpu workload:

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

             my $lxs = Sys::Statistics::Linux->new( Processes => 1 );
             sleep(1);
             my $stats = $lxs->get;
             my $procs = $stats->{Processes};

             my @top5 = (
                map  { $_->[0] }
                reverse sort { $a->[1] <=> $b->[1] }
                map  { [ $_, $procs->{$_}->{ttime} ] } keys %{$procs}
             )[0..4];

DEPENDENCIED
        UNIVERSAL
        UNIVERSAL::require
        Test::More
        Carp

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, 2007 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.

