NAME

Linux::Statistics - Collect linux system statistics.

SYNOPSIS

    use Linux::Statistics;

    my $obj = Linux::Statistics->new( SysInfo   => 1,
                                      ProcStats => 1,
                                      MemStats  => 1,
                                      PgSwStats => 1,
                                      NetStats  => 1,
                                      SockStats => 1,
                                      DiskStats => 1,
                                      DiskUsage => 1,
                                      LoadAVG   => 1,
                                      FileStats => 1,
                                      Processes => 1,
                                      TimeStamp => 1 );

    sleep(1);

    my $stats = $obj->getStats;

DESCRIPTION

This module collects system statistics like processor workload, memory usage and other
system informations from the /proc filesystem. It is tested on x86 hardware with the
distributions SuSE, SLES (s390 and s390x), Red Hat, Debian and Mandrake on kernel versions
2.4 and 2.6 but should also running on other linux distributions with the same kernel
release number. To run this module it is necessary to start it as root or another user
with the authorization to read the /proc filesystem and the /etc/passwd file.

STATISTICS

All options are identical with the functions and returns a multidimensional hash as a reference with the
collected system informations. There are two ways to collect the statistics. You can call the methods
new() and getStats() to collect all necessary data at the same time or you call the different
functions in single steps, but note that the functions ProcStats(), PgSwStats(), NetStats(),
DiskStats() and Processes() will return raw data and no deltas.

The functions SysInfo(), MemStats(), SockStats(), DiskUsage(), LoadAVG() and FileStats()
are no deltas. If you need only one of this informations you don't need to call new() and getStats().
Note that the TimeStamp is not a function and only available if you call getStats().

If you use the method new(), it checks the options and initialize all statistics that are needed to
calculate the deltas. The getStats() function collects all requested informations, calculate the
deltas and actualize the initalized values. This way making it possible that the method new() doesn't
must called again and again if you want to collect the statistics in a loop. The exception is that you must
call the method new() if you want to add or remove a option. In the near feature I think about a function
to add options.

NOTE

If you want to get useful statistics for the options ProcStats, NetStats, DiskStats, PgSwStats
and Processes then it's necessary to sleep for a while - at least one second - between the calls
of new() and getStats(). If you shouldn't do that it's possible that this statistics will be null.
The reason is that this statistics - remember - are deltas since the last time that the new method was
called and the call of getStats(). If you use a sleep interval for one or more seconds and some statistics
be null then your system seems to have a low workload.

Have a lot of fun with this module :-)

OPTIONS, FUNCTIONS

SysInfo, SysInfo()

Generated from F</proc/sys/kernel/{hostname,domainname,ostype,osrelease,version}>
and /proc/cpuinfo, /proc/meminfo, /proc/uptime.

   Hostname        -  This is the host name.
   Domain          -  This is the host domain name.
   Kernel          -  This is the kernel name.
   Release         -  This is the release number.
   Version         -  This is the version number.
   MemTotal        -  The total size of memory.
   SwapTotal       -  The total size of swap space.
   CountCPUs       -  The total (maybe logical) number of CPUs.
   Uptime          -  This is the uptime of the system.
   IdleTime        -  This is the idle time of the system.

ProcStats, ProcStats()

Generated from /proc/stat.

   User            -  Percentage of CPU utilization at the user level.
   Nice            -  Percentage of CPU utilization at the user level with nice priority.
   System          -  Percentage of CPU utilization at the system level.
   Idle            -  Percentage of time the CPU is in idle state.
   IOWait          -  Percentage of time the CPU is in idle state because an i/o operation is waiting for a disk.
   Total           -  Total percentage of CPU utilization at user and system level.
   New             -  Number of new processes that were produced per second.

MemStats, MemStats()

Generated from /proc/meminfo.

   MemUsed         -  Total size of used memory in kilobytes.
   MemFree         -  Total size of free memory in kilobytes.
   MemUsedPer      -  Total size of used memory in percent.
   MemTotal        -  Total size of memory in kilobytes.
   Buffers         -  Total size of buffers used from memory in kilobytes.
   Cached          -  Total size of cached memory in kilobytes.
   SwapUsed        -  Total size of swap space is used is kilobytes.
   SwapFree        -  Total size of swap space is free in kilobytes.
   SwapUsedPer     -  Total size of swap space is used in percent.
   SwapTotal       -  Total size of swap space in kilobytes.

PgSwStats, PgSwStats()

Generated from /proc/stat or /proc/vmstat.

   PageIn          -  Number of kilobytes the system has paged in from disk.
   PageOut         -  Number of kilobytes the system has paged out to disk.
   SwapIn          -  Number of kilobytes the system has swapped in from disk.
   SwapOut         -  Number of kilobytes the system has swapped out to disk.

NetStats, NetStats()

Generated from /proc/net/dev.

   RxBytes         -  Number of bytes received.
   RxPackets       -  Number of packets received.
   RxErrs          -  Number of errors that happend while received packets.
   RxDrop          -  Number of packets that were dropped.
   RxFifo          -  Number of FIFO overruns that happend on received packets.
   RxFrame         -  Number of carrier errors that happend on received packets.
   RxCompr         -  Number of compressed packets received.
   RxMulti         -  Number of multicast packets received.
   TxBytes         -  Number of bytes transmitted.
   TxPackets       -  Number of packets transmitted.
   TxErrs          -  Number of errors that happend while transmitting packets.
   TxDrop          -  Number of packets that were dropped.
   TxFifo          -  Number of FIFO overruns that happend on transmitted packets.
   TxColls         -  Number of collisions that were detected.
   TxCarr          -  Number of carrier errors that happend on transmitted packets.
   TxCompr         -  Number of compressed packets transmitted.

NetStatsSum

   This are just some summaries of NetStats/NetStats().

   RxBytes         -  Total number of bytes received.
   TxBytes         -  Total number of bytes transmitted.

SockStats, SockStats()

Generated from /proc/net/sockstat.

   Used            -  Total number of used sockets.
   Tcp             -  Number of tcp sockets in use.
   Udp             -  Number of udp sockets in use.
   Raw             -  Number of raw sockets in use.
   IpFrag          -  Number of ip fragments in use.

DiskStats, DiskStats()

Generated from /proc/diskstats or /proc/partitions.

   Major           -  The mayor number of the disk
   Minor           -  The minor number of the disk
   ReadRequests    -  Number of read requests that were made to physical disk.
   ReadBytes       -  Number of bytes that were read from physical disk.
   WriteRequests   -  Number of write requests that were made to physical disk.
   WriteBytes      -  Number of bytes that were written to physical disk.
   TotalRequests   -  Total number of requests were made from/to physical disk.
   TotalBytes      -  Total number of bytes transmitted from/to physical disk.

DiskStatsSum

   This are just some summaries of DiskStats/DiskStats().

   ReadRequests    -  Total number of read requests were made to all physical disks.
   ReadBytes       -  Total number of bytes reads from all physical disks.
   WriteRequests   -  Total number of write requests were made to all physical disks.
   WriteBytes      -  Total number of bytes written to all physical disks.
   Requests        -  Total number of requests were made from/to all physical disks.
   Bytes           -  Total number of bytes transmitted from/to all physical disks.

DiskUsage, DiskUsage()

Generated with F</bin/df -k>.

   Total           -  The total size of the disk.
   Usage           -  The used disk space in kilobytes.
   Free            -  The free disk space in kilobytes.
   UsagePer        -  The used disk space in percent.
   MountPoint      -  The moint point of the disk.

LoadAVG, LoadAVG()

Generated with /proc/loadavg.

   AVG_1           -  The average processor workload of the last minute.
   AVG_5           -  The average processor workload of the last five minutes.
   AVG_15          -  The average processor workload of the last fifteen minutes.
   RunQueue        -  The number of processes waiting for runtime.
   Count           -  The total amount of processes on the system.

FileStats, FileStats()

Generated with F</proc/sys/fs/file-nr>, F</proc/sys/fs/inode-nr> and F</proc/sys/fs/dentry-state>.

   fhAlloc         -  Number of allocated file handles.
   fhFree          -  Number of free file handles.
   fhMax           -  Number of maximum file handles.
   inAlloc         -  Number of allocated inodes.
   inFree          -  Number of free inodes.
   inMax           -  Number of maximum inodes.
   Dentries        -  Dirty directory cache entries.
   Unused          -  Free diretory cache size.
   AgeLimit        -  Time in seconds the dirty cache entries can be reclaimed.
   WantPages       -  Pages that are requested by the system when memory is short.

Processes, Processes()

Generated with /proc/<number>/statm, /proc/<number>/stat,
/proc/<number>/status, /proc/<number>/cmdline and /etc/passwd.

   PPid            -  The parent process ID of the process.
   Owner           -  The owner name of the process.
   State           -  The status of the process.
   PGrp            -  The group ID of the process.
   Session         -  The session ID of the process.
   TTYnr           -  The tty the process use.
   MinFLT          -  The number of minor faults the process made.
   CMinFLT         -  The number of minor faults the child process made.
   MayFLT          -  The number of mayor faults the process made.
   CMayFLT         -  The number of mayor faults the child process made.
   CUTime          -  The number of jiffies the process waited for childrens have been scheduled in user mode.
   STime           -  The number of jiffies the process have beed scheduled in kernel mode.
   UTime           -  The number of jiffies the process have beed scheduled in user mode.
   CSTime          -  The number of jiffies the process waited for childrens have been scheduled in kernel mode.
   Prior           -  The priority of the process (+15).
   Nice            -  The nice level of the process.
   StartTime       -  The time in jiffies the process started after system boot.
   ActiveTime      -  The time in D:H:M (days, hours, minutes) the process is active.
   VSize           -  The size of virtual memory of the process.
   NSwap           -  The size of swap space of the process.
   CNSwap          -  The size of swap space of the childrens of the process.
   CPU             -  The CPU number the process was last executed on.
   Size            -  The total program size of the process.
   Resident        -  Number of resident set size, this includes the text, data and stack space.
   Share           -  Total size of shared pages of the process.
   TRS             -  Total text size of the process.
   DRS             -  Total data/stack size of the process.
   LRS             -  Total library size of the process.
   DT              -  Total size of dirty pages of the process (unused since kernel 2.6).
   Comm            -  Command of the process.
   CMDLINE         -  Command line of the process.
   Pid             -  The process ID.

TimeStamp (the time stamp is only available if you call the function getStats())

Generated with localtime(time).

   Date            -  The current date.
   Time            -  The current time.

EXAMPLES

You can find very a simple script for tests under F<Linux-Statistics-1.14/Examples/>.
The script calls SimpleCheck and shows you the collected data with Data::Dumper.
The following example scripts lie under F<Linux-Statistics-1.14/Examples/> as well.

A very simple perl script could looks like this:

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

         my $obj = Linux::Statistics->new( ProcStats => 1 );
         sleep(1);
         my $stats = $obj->getStats;

         print "Statistics for ProcStats\n";
         print "  User      $stats->{ProcStats}->{User}\n";
         print "  Nice      $stats->{ProcStats}->{Nice}\n";
         print "  System    $stats->{ProcStats}->{System}\n";
         print "  Idle      $stats->{ProcStats}->{Idle}\n";
         print "  IOWait    $stats->{ProcStats}->{IOWait}\n";
         print "  Total     $stats->{ProcStats}->{Total}\n";
         print "  New       $stats->{ProcStats}->{New}\n";

Example to collect network statistics with a nice output:

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

         my $obj = Linux::Statistics->new( NetStats => 1 );
         sleep(1);
         my $stats = $obj->getStats;

         my @list = qw( RxBytes  RxPackets  RxErrs   RxDrop
                        RxFifo   RxFrame    RxCompr  RxMulti
                        TxBytes  TxPackets  TxErrs   TxDrop
                        TxFifo   TxColls    TxCarr   TxCompr );

         print ' ' x 6;
         printf '%12s', $_ for @list;
         print "\n";

         foreach my $device (keys %{$stats->{NetStats}}) {
            printf '%-6s', $device;
            printf '%12s', $stats->{NetStats}->{$device}->{$_} for @list;
            print "\n";
         }

         print "\nTotal network statistics:\n";

         while (my ($key,$value) = each %{$stats->{NetStatsSum}}) {
            printf '  %-12s', $key;
            printf '%12s', "$value\n";
         }

Example to show a process list:

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

         my $obj = Linux::Statistics->new( Processes => 1 );
         sleep(1);
         my $stats = $obj->getStats;

         printf '%-12s', $_ for qw(Pid PPid Owner State Size VSize CMDLINE);
         print "\n";

         foreach my $pid (keys %{$stats->{Processes}}) {
            printf '%-12s', $stats->{Processes}->{$pid}->{$_} for qw(Pid PPid Owner State Size VSize CMDLINE);
            print "\n";
         }

You can collect the statistics in a loop as well:

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

         $| = 1;

         my $obj = Linux::Statistics->new( ProcStats => 1, TimeStamp => 1 );

         print "Report/Statistic for ProcStats\n";
         printf '%8s', $_ for qw(Time User System Total Nice IOWait Idle New);
         print "\n";

         while (1) {
            sleep(1);
            my $stats = $obj->getStats;

            print "$stats->{TimeStamp}->{Time}";
            printf '%8s', $stats->{ProcStats}->{$_} for qw(User System Total Nice IOWait Idle New);
            print "\n";
         }

It is possible to create a hash reference with options as well:

         my $options = {
            SysInfo   => 1,
            ProcStats => 1,
            MemStats  => 1,
            PgSwStats => 1,
            NetStats  => 1,
            SockStats => 1,
            DiskStats => 1,
            DiskUsage => 1,
            LoadAVG   => 1,
            FileStats => 1,
            Processes => 1,
            TimeStamp => 1,
         };

         my $obj = Linux::Statistics->new( $options );
         sleep(1);
         my $stats = $obj->getStats;

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 Linux::Statistics;
         use Data::Dumper;

         my $obj = Linux::Statistics->new( ProcStats => 1 );
         sleep(1);
         my $stats = $obj->getStats;

         print Dumper($stats);

One simple example for the call without new() and getStats():

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

         my $stats = {};

         # remember... ProcStats(), PgSwStats(), NetStats(),
         # DiskStats() and Processes() are raw data and no deltas!

         for my $opt (qw(SysInfo ProcStats MemStats PgSwStats SockStats DiskUsage LoadAVG FileStats Processes)) {
            $stats->{$opt} = Linux::Statistics->$opt;
         }

         # NetStats() and DiskStats() returns two hash references.

         for my $opt (qw(NetStats DiskStats)) {
            ($stats->{$opt},$stats->{"${opt}Sum"}) = Linux::Statistics->$opt;
         }

         # have a look on the structure

         print Dumper($stats);

EXPORTS

No exports.

SEE ALSO

proc(5)

F</usr/src/linux/Documentation/filesystems/proc.txt>

REPORTING BUGS

Please report all bugs to <jschulz@bloonix.de>.

EXPANSIONS

If there are statistics you need but not generated by this module please send me an email
with your wishs or a function ready to built in :-).

Maybe this module do not runs on your architecture fine because there are a lot of differences
between the /proc filesystems of your arch and a simple x86 system. In this case it would be
fine if you contact me and we looks for a solution.

AUTHOR

Jonny Schulz <jschulz@bloonix.de>.

COPYRIGHT

Copyright (c) 2005, 2006 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.

