NAME Sys::Statistics::Linux - Front-end module to collect 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 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. 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), Red Hat, Debian, Asianux, Slackware and Mandrake on kernel versions 2.4 and 2.6 and should run on all linux kernels with a default vanilla kernel as well. It is possible that this module doesn't run on all distributions if the procfs is too much modified. For example the linux kernel 2.4 can compiled with the option "CONFIG_BLK_STATS". It is possible to activate or deactivate the block statistics for devices with this option. These statistics doesn't exist in /proc/partitions if this option isn't activated. Since linux kernel 2.5 these statistics are in /proc/diskstats. 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()". 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 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: -1 - set pause on statistics but wouldn't delete them 0 - delete statistics and destroy the object 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 ] } ); It's only possible to set "init" to 1 or 2. 1 would init statistics, 2 not but both values would create a new "Processes" object. 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 = new Sys::Statistics::Linux; 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( CpuStats => -1, # activated, but paused, wouldn't delete the object Processes => 0, # deactivate - would delete the statistics and destroy the object 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"; 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(SysStats => 0); # $stats contains CpuStats and MemStats sleep(1); $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); 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]; Take a look into the the examples directory of the distribution for some examples with a nice output. :-) DEPENDENCIED Test::More Carp EXPORTS No exports. TODOS * pstree * Are there any wishs from your side? Send me a mail! REPORTING BUGS Please report all bugs to . AUTHOR Jonny Schulz . 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.