NAME

Linux::Statistics - collect system statistics

SYNOPSIS

use Linux::Statistics;

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

sleep($sec);

$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 it 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.

NOTE THAT ...

it is necessary to sleep for at least of one second between the calls of new() and getStats(),
if you want to get useful statistics for ProcStats, NetStats, DiskStats and PgSwStats. If you
start some statistics for ProcStats you should do that in any case, otherwise you can get a
message like this:

Illegal division by zero at ...

The reason is that this statistics are deltas since the last time that the new method was called.

OPTIONS

Each option returns a hash reference with the collected system informations.

SysInfo

Generated from /proc/sys/kernel/hostname *domainname *ostype *osrelease *version
and /proc/sysinfo, /proc/cpuinfo, /proc/meminfo, /proc/uptime.

   SysHostname           -  This is the host name.
   SysDomain             -  This is the host domain name.
   SysKernel             -  This is the kernel name.
   SysRelease            -  This is the release number.
   SysVersion            -  This is the version number.
   SysMemTotal           -  The total size of memory.
   SysSwapTotal          -  The total size of swap space.
   SysCPU_Power          -  The power of the CPUs in mhz or bogomips.
   SysCountCPUs          -  The total number of CPUs.
   SysModelName          -  The model name.
   SysUptime             -  This is the uptime of the system.
   SysIdleTime           -  This is the idle time of the system idletime.

ProcStats

Generated from /proc/stat.

   ProcUser              -  Percentage of CPU utilization at the user level.
   ProcNice              -  Percentage of CPU utilization at the user level with nice priority.
   ProcSystem            -  Percentage of CPU utilization at the system level.
   ProcIdle              -  Percentage of time the CPU is in idle state.
   ProcIOWait            -  Percentage of time the CPU is in idle state because an i/o operation is waiting for a disk.
   ProcTotal             -  Total percentage of CPU utilization at user and system level.
   ProcNew               -  Number of new processes that were produced per second.

MemStats

Generated from /proc/meminfo.

   MemUsed               -  Total size of used memory in kilobytes.
   MemFree               -  Total size of free memory in kilobytes.
   MemUsedPro            -  Total size of used memory in percent.
   MemTotal              -  Total size of memory in kilobytes.
   MemBuffers            -  Total size of buffers used from memory in kilobytes.
   MemCached             -  Total size of cached memory in kilobytes.
   MemSwapUsed           -  Total size of swap space is used is kilobytes.
   MemSwapFree           -  Total size of swap space is free in kilobytes.
   MemSwapUsedPro        -  Total size of swap space is used in percent.
   MemSwapTotal          -  Total size of swap space in kilobytes.

PgSwStats

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

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

NetStats

Generated from /proc/net/dev.

   NetRxBytes            -  Number of bytes received per second.
   NetRxPackets          -  Number of packets received per second.
   NetRxErrs             -  Number of errors that happend per second while received packets.
   NetRxDrop             -  Number of packets that were dropped per second.
   NetRxFifo             -  Number of FIFO overruns that happend per second on received packets.
   NetRxFrame            -  Number of carrier errors that happend per second on received packets.
   NetRxCompr            -  Number of compressed packets received per second.
   NetRxMulti            -  Number of multicast packets received per second.
   NetTxBytes            -  Number of bytes transmitted per second.
   NetTxPacktes          -  Number of packets transmitted per second.
   NetTxErrs             -  Number of errors that happend while transmitting packets.
   NetTxDrop             -  Number of packets that were dropped per second.
   NetTxFifo             -  Number of FIFO overruns that happend per second on transmitted packets.
   NetTxColls            -  Number of collisions that were detected.
   NetTxCarr             -  Number of carrier errors that happend per second on transmitted packets.
   NetTxCompr            -  Number of compressed packets transmitted per second.

NetStatsSum

   This are just some summaries of NetStats.

   NetRxBytes            -  Total number of bytes received per second.
   NetTxBytes            -  Total number of bytes transmitted per second.

SockStats

Generated from /proc/net/sockstat.

   SockTcpSockets        -  Number of tcp sockets in use.
   SockUdpSockets        -  Number of udp sockets in use.
   SockRawSockets        -  Number of raw sockets in use.
   SockTotalSockets      -  Total number of sockets in use.

DiskStats

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

   DiskMajor             -  The mayor number of the disk
   DiskMinor             -  The minor number of the disk
   DiskReadRequests      -  Number of read requests that were made per second to physical disk.
   DiskReadBytes         -  Number of bytes that were read per second from physical disk.
   DiskWriteRequests     -  Number of write requests that were made per second to physical disk.
   DiskWriteBytes        -  Number of bytes that were written per second to physical disk.
   DiskTotalRequests     -  Total number of requests were made per second from/to physical disk.
   DiskTotalBytes        -  Total number of bytes transmitted per second from/to physical disk.

DiskStatsSum

   This are just some summaries of DiskStats.

   DiskReadRequests      -  Total number of read requests were made per second to all physical disks.
   DiskReadBytes         -  Total number of bytes reads per second from all physical disks.
   DiskWriteRequests     -  Total number of write requests were made per second to all physical disks.
   DiskWriteBytes        -  Total number of bytes written per second to all physical disks.
   DiskRequests          -  Total number of requests were made per second from/to all physical disks.
   DiskBytes             -  Total number of bytes transmitted per second from/to all physical disks.

DiskUsage

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

   DiskU_Total           -  The total size of the disk.
   DiskU_Usage           -  The used disk space in kilobytes.
   DiskU_Free            -  The free disk space in kilobytes.
   DiskU_UsagePro        -  The used disk space in percent.
   DiskU_MountPoint      -  The moint point of the disk.

LoadAVG

Generated with /proc/loadavg.

   ProcAVG_1             -  The average processor workload of the last minute.
   ProcAVG_5             -  The average processor workload of the last five minutes.
   ProcAVG_15            -  The average processor workload of the last fifteen minutes.
   ProcRunQueue          -  The number of processes waiting for runtime.
   ProcCount             -  The total amount of processes on the system.

Processes

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

   sProcPPid             -  The parent process ID of the process.
   sProcOwner            -  The owner name of the process.
   sProcState            -  The status of the process.
   sProcPGrp             -  The group ID of the process.
   sProcSession          -  The session ID of the process.
   sProcTTYnr            -  The tty the process use.
   sProcMinFLT           -  The number of minor faults the process made per second.
   sProcCMinFLT          -  The number of minor faults the child process made per second.
   sProcMayFLT           -  The number of mayor faults the process made per second.
   sProcCMayFLT          -  The number of mayor faults the child process made per second.
   sProcCUTime           -  The number of jiffies the process waited for childrens have been scheduled in user mode.
   sProcSTime            -  The number of jiffies the process have beed scheduled in kernel mode.
   sProcUTime            -  The number of jiffies the process have beed scheduled in user mode.
   sProcCSTime           -  The number of jiffies the process waited for childrens have been scheduled in kernel mode.
   sProcPrior            -  The priority of the process (+15).
   sProcNice             -  The nice level of the process.
   sProcStartTime        -  The time in jiffies the process started after system boot.
   sProcVSize            -  The size of virtual memory of the process.
   sProcNSwap            -  The size of swap space of the process.
   sProcCNSwap           -  The size of swap space of the childrens of the process.
   sProcProc             -  The CPU number the process was last executed on.
   sProcSize             -  The total program size of the process.
   sProcResident         -  Number of resident set size, this includes the text, data and stack space.
   sProcShare            -  Total size of shared pages of the process.
   sProcTRS              -  Total text size of the process.
   sProcDRS              -  Total data/stack size of the process.
   sProcLRS              -  Total library size of the process.
   sProcDT               -  Total size of dirty pages of the process (unused since kernel 2.6).
   sProcComm             -  Command of the process.
   sProcCMDLINE          -  Command line of the process.
   sProcPid              -  The process ID.

TimePoint

Generated with localtime(time).

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

EXAMPLES

A very simple perl script could looks like this:

         #!/usr/bin/perl -w
         use strict;
         use Linux::Statistics;

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

         print "Report/Statistic for ProcStats\n";
         print "  ProcUser      $stats->{ProcStats}->{ProcUser}\n";
         print "  ProcNice      $stats->{ProcStats}->{ProcNice}\n";
         print "  ProcSystem    $stats->{ProcStats}->{ProcSystem}\n";
         print "  ProcIdle      $stats->{ProcStats}->{ProcIdle}\n";
         print "  ProcIOWait    $stats->{ProcStats}->{ProcIOWait}\n";
         print "  ProcTotal     $stats->{ProcStats}->{ProcTotal}\n";
         print "  ProcNew       $stats->{ProcStats}->{ProcNew}\n";

Or this:

         #!/usr/bin/perl -w
         use strict;
         use Linux::Statistics;

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

         foreach my $device (keys %{$stats->{NetStats}}) {
            print "Statistics for device $device ...\n";

            while (my ($key,$value) = each %{$stats->{NetStats}->{$device}}) {
               print ' ' x 2 . "$key" . ' ' x (30-length($key)) . "$value\n";
            }
         }

         print "\nTotal network statistics ...\n";

         while (my ($key,$value) = each %{$stats->{NetStatsSum}}) {
            print ' ' x 2 . "$key" . ' ' x (30-length($key)) . "$value\n";
         }

This also:

         #!/usr/bin/perl -w
         use strict;
         use Linux::Statistics;

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

         # print a formated header

         print "$_". ' ' x (12-length($_)) for qw/PID PPID OWNER STATE SIZE VSIZE COMMAND/;
         print "\n";

         foreach my $pid (keys %{$stats->{Processes}}) {
            print "$stats->{Processes}->{$pid}->{$_}". ' ' x (12-length($stats->{Processes}->{$pid}->{$_}))
               for qw/sProcPid sProcPPid sProcOwner sProcState sProcSize sProcVSize sProcCMDLINE/;
            print "\n";
         }

It is also possible to create a hash reference with options.

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

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

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

         #!/usr/bin/perl -w
         use strict;
         use Linux::Statistics;
         use Data::Dumper;

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

         print Dumper($stats);

Have a lot of fun with this module :-)

SEE ALSO

The manpage of proc(5) or I</usr/src/linux/Documentation/filesystems/proc.txt>.

AUTHOR

Jonny Schulz. Please report all bugs to <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.

