NAME
    Sys::Statistics::Linux - Main package to collect linux system
    statistics.

SYNOPSIS
       use Sys::Statistics::Linux;

       my $lxs = new Sys::Statistics::Linux;

       $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
    This module is the main package from the distribution
    Sys::Statistics::Linux and collects different linux system informations
    like processor workload, memory usage, network and disk statisitcs and
    other system informations. Refer to the documentation of the
    distribution modules to get more informations about all possible
    statistics and system informations.

DELTAS
    The options "CpuStats", "ProcStats", "PgSwStats", "NetStats",
    "DiskStats" and "Processes" are deltas, for this reason it's necessary
    to initialize the statistics first, before the data be generated with
    "get()". The statistics can be initialized with the methods "new()",
    "set()" and "init()". Each 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 that you need to sleep for while - at least for one
    second - before you call "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 this informations
    you don't need to sleep before the call of "get()".

    The "get()" function collects all requested informations and returns a
    hash reference with the statistics. 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 deactivate -
    respectively delete - statistics with "set()" and re-init all statistics
    with "init()".

    The options must be set with a BOOLEAN value (1|0).

       1 - activate (initialize)
       0 - deactivate (delete)

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

       SysInfo     -  Collect system informations             with L<Sys::Statistics::Linux::SysInfo>.
       CpuStats    -  Collect cpu statistics                  with L<Sys::Statistics::Linux::CpuStats>.
       ProcStats   -  Collect process statistics              with L<Sys::Statistics::Linux::ProcStats>.
       MemStats    -  Collect memory statistics               with L<Sys::Statistics::Linux::MemStats>.
       PgSwStats   -  Collect paging and swapping statistics  with L<Sys::Statistics::Linux::PgSwStats>.
       NetStats    -  Collect net statistics                  with L<Sys::Statistics::Linux::NetStats>.
       SockStats   -  Collect socket statistics               with L<Sys::Statistics::Linux::SockStats>.
       DiskStats   -  Collect disk statistics                 with L<Sys::Statistics::Linux::DiskStats>.
       DiskUsage   -  Collect the disk usage                  with L<Sys::Statistics::Linux::DiskUsage>.
       LoadAVG     -  Collect the load average                with L<Sys::Statistics::Linux::LoadAVG>.
       FileStats   -  Collect inode statistics                with L<Sys::Statistics::Linux::FileStats>.
       Processes   -  Collect process statistics              with L<Sys::Statistics::Linux::Processes>.

METHODS
  All methods
       C<new()>
       C<set()>
       C<get()>
       C<settime()>
       C<gettime()>

  new()
    Call "new()" to create a new Statistic object. Necessary statistics will
    be initialized.

    Without options

             my $lxs = new Sys::Statistics::Linux;

    Or with options

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

    Will 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 (initialize) or deactivate (delete) options.

             $lxs->set(
                CpuStats => 1, # activate
                SysInfo  => 0, # deactivate
             );

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

             my %options = (
                CpuStats => 1,
                MemStats => 1
             );

             $lxs->set(\%options);

    Activate options with "set()" will initialize necessary statistics.

             $lxs->set(CpuStats => 1); # initialize it
             $lxs->set(CpuStats => 1); # initialize it again

  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 set to 1.

             $lxs->init;

  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()
    Call "gettime()" returns the POSIX formatted time stamp. If a time
    format isn't set then the default time stamp will be set automatically.
    You can also set a timeformat with "gettime()".

             my $time_stamp = $lxs->gettime;

    Or

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

    Or print it.

             print $lxs->gettime, "\n";

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";

    Example to collect network statistics with a nice output:

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

             $| = 1;

             my $header  = 20;
             my $average = 1;
             my $columns = 8;
             my $options = { NetStats => 1 };

             my @order = qw(
                rxbyt rxpcks rxerrs rxdrop rxfifo rxframe rxcompr rxmulti
                txbyt txpcks txerrs txdrop txfifo txcolls txcarr txcompr
             );

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

             my $h = $header;

             while (1) {
                sleep($average);
                my $stats = $lxs->get;
                if ($h == $header) {
                   printf "%${columns}s", $_ for ('iface', @order);
                   print "\n";
                }
                foreach my $device (keys %{$stats->{NetStats}}) {
                   my $dstat = $stats->{NetStats}->{$device};
                   printf "%${columns}s", $device;
                   printf "%${columns}s", $dstat->{$_} for @order;
                   print "\n";
                }
                $h = $header if --$h == 0;
             }

    Activate and deactivate statistics:

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

             my $lxs = new Sys::Statistics::Linux;

             # set the options
             $lxs->set(
                SysInfo  => 1,
                CpuStats => 1,
                MemStats => 1
             );

             # sleep to get useful statistics for CpuStats
             sleep(1);

             # $stats contains SysInfo, CpuStats and MemStats
             my $stats = $lxs->get;
             print Dumper($stats);

             # we deactivate CpuStats
             $lxs->set(CpuStats => 0);

             # $stats contains SysInfo and MemStats
             $stats = $lxs->get;
             print Dumper($stats);

    Set and get a time stamp:

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

             my $lxs = new Sys::Statistics::Linux;
             $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);

    Take a look into the the examples directory of the distribution for some
    examples with a nice output. :-)

EXPORTS
    No exports.

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.

