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

SYNOPSIS
        use Sys::Statistics::Linux;

        my $lxs = Sys::Statistics::Linux->new(
            sysinfo   => 1,
            cpuinfo   => 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;

        # $stat is a Sys::Statistics::Linux::Compilation object
        my $stat = $lxs->get;

        foreach my $key ($stat->loadavg) {
            print $key, " ", $stat->loadavg($key), "\n";
        }

DESCRIPTION
    Sys::Statistics::Linux is a front-end module and gather 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 and to store different statistics into a database. So I though 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 default vanilla kernels. It is tested on
    x86 hardware with the distributions RHEL, Fedora, Debian, Ubuntu,
    Asianux, Slackware, Mandriva, SuSE (SuSE on s390 and s390x architecture
    as well but a long time ago) and openSUSE 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 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.

DELTAS
    The statistics for "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 1 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 METHOD
    section to get more information about the calls of "new()", "set()",
    "init()" 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
    statistics for "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()" prepares all requested statistics and returns the
    statistics as a "Sys::Statistics::Linux::Compilation" object. The inital
    statistics will be updated.

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

  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 a
    Sys::Statistics::Linux::Compilation object.

        my $stat = $lxs->get;

    Now the statistcs are available with

        $stat->cpustats

        # or

        $stat->{cpustats}

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

  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 average values 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 the following example would be better for you:

        # don't initiate cpustats
        my $lxs = Sys::Statistics::Linux->new( cpustats => 2 );

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

  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 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're not sure you can use the the "Data::Dumper" module to learn
    more about the hash structure:

        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 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 $proc = $stat->processes;

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

BACKWARD COMPATIBILITY
    The old options and keys - CpuStats, NetStats, etc - are still available
    but 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.

PREREQUISITES
        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.

