1Sys::Statistics::Linux(U3s)er Contributed Perl DocumentatSiyosn::Statistics::Linux(3)
2
3
4

NAME

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

SYNOPSIS

9           use Sys::Statistics::Linux;
10
11           my $lxs = Sys::Statistics::Linux->new(
12               sysinfo   => 1,
13               cpustats  => 1,
14               procstats => 1,
15               memstats  => 1,
16               pgswstats => 1,
17               netstats  => 1,
18               sockstats => 1,
19               diskstats => 1,
20               diskusage => 1,
21               loadavg   => 1,
22               filestats => 1,
23               processes => 1,
24           );
25
26           sleep 1;
27           my $stat = $lxs->get;
28

DESCRIPTION

30       Sys::Statistics::Linux is a front-end module and gather different linux
31       system information like processor workload, memory usage, network and
32       disk statistics and a lot more. Refer the documentation of the
33       distribution modules to get more information about all possible
34       statistics.
35

MOTIVATION

37       My motivation is very simple... every linux administrator knows the
38       well-known tool sar of sysstat.  It helps me a lot of time to search
39       for system bottlenecks and to solve problems, but it's hard to parse
40       the output if you want to store the statistics into a database. So I
41       thought to develope Sys::Statistics::Linux. It's not a replacement but
42       it should make it simpler to you to write your own system monitor.
43
44       If Sys::Statistics::Linux doesn't provide statistics that are strongly
45       needed then let me know it.
46

TECHNICAL NOTE

48       This distribution collects statistics by the virtual /proc filesystem
49       (procfs) and is developed on the default vanilla kernel. It is tested
50       on x86 hardware with the distributions RHEL, Fedora, Debian, Ubuntu,
51       Asianux, Slackware, Mandriva and openSuSE (SLES on zSeries as well but
52       a long time ago) on kernel versions 2.4 and/or 2.6. It's possible that
53       it doesn't run on all linux distributions if some procfs features are
54       deactivated or too much modified.  As example the linux kernel 2.4 can
55       compiled with the option "CONFIG_BLK_STATS" what turn on or off block
56       statistics for devices.
57
58       Don't give up if some of the modules doesn't run on your hardware! Tell
59       me what's wrong and I will try to solve it! You just have to make the
60       first move and to send me a mail. :-)
61

VIRTUAL MACHINES

63       Note that if you try to install or run "Sys::Statistics::Linux" under
64       virtual machines on guest systems that some statistics are not
65       available, such as "SockStats", "PgSwStats" and "DiskStats". The reason
66       is that not all /proc data are passed to the guests.
67
68       If the installation fails then try to force the installation with
69
70           cpan> force install Sys::Statistics::Linux
71
72       and notice which tests fails, because this statistics maybe not
73       available on the virtual machine - sorry.
74

DELTAS

76       The statistics for "CpuStats", "ProcStats", "PgSwStats", "NetStats",
77       "DiskStats" and "Processes" are deltas, for this reason it's necessary
78       to initialize the statistics before the data can be prepared by
79       "get()". These statistics can be initialized with the methods "new()",
80       "set()" and "init()". For any option that is set to 1, the statistics
81       will be initialized by the call of "new()" or "set()". The call of
82       init() re-initialize all statistics that are set to 1 or 2.  By the
83       call of "get()" the initial statistics will be updated automatically.
84       Please refer the section "METHODS" to get more information about the
85       usage of "new()", "set()", "init()" and "get()".
86
87       Another exigence is to sleep for a while - at least for one second -
88       before the call of "get()" if you want to get useful statistics. The
89       statistics for "SysInfo", "MemStats", "SockStats", "DiskUsage",
90       "LoadAVG" and "FileStats" are no deltas. If you need only one of these
91       information you don't need to sleep before the call of "get()".
92
93       The method "get()" prepares all requested statistics and returns the
94       statistics as a Sys::Statistics::Linux::Compilation object. The inital
95       statistics will be updated.
96

MANUAL PROC(5)

98       The Linux Programmer's Manual
99
100           http://www.kernel.org/doc/man-pages/online/pages/man5/proc.5.html
101
102       If you have questions or don't understand the sense of some statistics
103       then take a look into this awesome documentation.
104

OPTIONS

106       All options are identical with the package names of the distribution in
107       lowercase. To activate the gathering of statistics you have to set the
108       options by the call of "new()" or "set()".  In addition you can
109       deactivate statistics with "set()".
110
111       The options must be set with one of the following values:
112
113           0 - deactivate statistics
114           1 - activate and init statistics
115           2 - activate statistics but don't init
116
117       In addition it's possible to pass a hash reference with options.
118
119           my $lxs = Sys::Statistics::Linux->new(
120               processes => {
121                   init => 1,
122                   pids => [ 1, 2, 3 ]
123               },
124               netstats => {
125                   init => 1,
126                   initfile => $file,
127               },
128           );
129
130       Option "initfile" is useful if you want to store initial statistics on
131       the filesystem.
132
133           my $lxs = Sys::Statistics::Linux->new(
134               cpustats => {
135                   init     => 1,
136                   initfile => '/tmp/cpustats.yml',
137               },
138               diskstats => {
139                   init     => 1,
140                   initfile => '/tmp/diskstats.yml',
141               },
142               netstats => {
143                   init     => 1,
144                   initfile => '/tmp/netstats.yml',
145               },
146               pgswstats => {
147                   init     => 1,
148                   initfile => '/tmp/pgswstats.yml',
149               },
150               procstats => {
151                   init     => 1,
152                   initfile => '/tmp/procstats.yml',
153               },
154           );
155
156       Example:
157
158           #!/usr/bin/perl
159           use strict;
160           use warnings;
161           use Sys::Statistics::Linux;
162
163           my $lxs = Sys::Statistics::Linux->new(
164               pgswstats => {
165                   init => 1,
166                   initfile => '/tmp/pgswstats.yml'
167               }
168           );
169
170           $lxs->get(); # without to sleep
171
172       The initial statistics are stored to the temporary file:
173
174           #> cat /tmp/pgswstats.yml
175           ---
176           pgfault: 397040955
177           pgmajfault: 4611
178           pgpgin: 21531693
179           pgpgout: 49511043
180           pswpin: 8
181           pswpout: 272
182           time: 1236783534.9328
183
184       Every time you call the script the initial statistics are loaded/stored
185       from/to the file.  This could be helpful if you doesn't run it as
186       daemon and if you want to calculate the average load of your system
187       since the last call. Do you understand? I hope so :)
188
189       To get more information about the statistics refer the different
190       modules of the distribution.
191
192           sysinfo     -  Collect system information              with Sys::Statistics::Linux::SysInfo.
193           cpustats    -  Collect cpu statistics                  with Sys::Statistics::Linux::CpuStats.
194           procstats   -  Collect process statistics              with Sys::Statistics::Linux::ProcStats.
195           memstats    -  Collect memory statistics               with Sys::Statistics::Linux::MemStats.
196           pgswstats   -  Collect paging and swapping statistics  with Sys::Statistics::Linux::PgSwStats.
197           netstats    -  Collect net statistics                  with Sys::Statistics::Linux::NetStats.
198           sockstats   -  Collect socket statistics               with Sys::Statistics::Linux::SockStats.
199           diskstats   -  Collect disk statistics                 with Sys::Statistics::Linux::DiskStats.
200           diskusage   -  Collect the disk usage                  with Sys::Statistics::Linux::DiskUsage.
201           loadavg     -  Collect the load average                with Sys::Statistics::Linux::LoadAVG.
202           filestats   -  Collect inode statistics                with Sys::Statistics::Linux::FileStats.
203           processes   -  Collect process statistics              with Sys::Statistics::Linux::Processes.
204

METHODS

206   new()
207       Call "new()" to create a new Sys::Statistics::Linux object. You can
208       call "new()" with options.  This options would be passed to the method
209       "set()".
210
211       Without options
212
213           my $lxs = Sys::Statistics::Linux->new();
214
215       Or with options
216
217           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
218
219       Would do nothing
220
221           my $lxs = Sys::Statistics::Linux->new( cpustats => 0 );
222
223       It's possible to call "new()" with a hash reference of options.
224
225           my %options = (
226               cpustats => 1,
227               memstats => 1
228           );
229
230           my $lxs = Sys::Statistics::Linux->new(\%options);
231
232   set()
233       Call "set()" to activate or deactivate options.
234
235       The following example would call "new()" and initialize
236       "Sys::Statistics::Linux::CpuStats" and delete the object of
237       "Sys::Statistics::Linux::SysInfo".
238
239           $lxs->set(
240               processes =>  0, # deactivate this statistic
241               pgswstats =>  1, # activate the statistic and calls new() and init() if necessary
242               netstats  =>  2, # activate the statistic and call new() if necessary but not init()
243           );
244
245       It's possible to call "set()" with a hash reference of options.
246
247           my %options = (
248               cpustats => 2,
249               memstats => 2
250           );
251
252           $lxs->set(\%options);
253
254   get()
255       Call "get()" to get the collected statistics. "get()" returns a
256       Sys::Statistics::Linux::Compilation object.
257
258           my $lxs  = Sys::Statistics::Linux->new(\%options);
259           sleep(1);
260           my $stat = $lxs->get();
261
262       Or you can pass the time to sleep with the call of "get()".
263
264           my $stat = $lxs->get($time_to_sleep);
265
266       Now the statistcs are available with
267
268           $stat->cpustats
269
270           # or
271
272           $stat->{cpustats}
273
274       Take a look to the documentation of Sys::Statistics::Linux::Compilation
275       for more information.
276
277   init()
278       The call of "init()" initiate all activated statistics that are
279       necessary for deltas. That could be helpful if your script runs in a
280       endless loop with a high sleep interval. Don't forget that if you call
281       "get()" that the statistics are deltas since the last time they were
282       initiated.
283
284       The following example would calculate average statistics for 30
285       minutes:
286
287           # initiate cpustats
288           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
289
290           while ( 1 ) {
291               sleep(1800);
292               my $stat = $lxs->get;
293           }
294
295       If you just want a current snapshot of the system each 30 minutes and
296       not the average then the following example would be better for you:
297
298           # do not initiate cpustats
299           my $lxs = Sys::Statistics::Linux->new( cpustats => 2 );
300
301           while ( 1 ) {
302               $lxs->init;              # init the statistics
303               my $stat = $lxs->get(1); # get the statistics
304               sleep(1800);             # sleep until the next run
305           }
306
307       If you want to write a simple command line utility that prints the
308       current workload to the screen then you can use something like this:
309
310           my @order = qw(user system iowait idle nice irq softirq total);
311           printf "%-20s%8s%8s%8s%8s%8s%8s%8s%8s\n", 'time', @order;
312
313           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
314
315           while ( 1 ){
316               my $cpu  = $lxs->get(1)->cpustats;
317               my $time = $lxs->gettime;
318               printf "%-20s%8s%8s%8s%8s%8s%8s%8s%8s\n",
319                   $time, @{$cpu->{cpu}}{@order};
320           }
321
322   settime()
323       Call "settime()" to define a POSIX formatted time stamp, generated with
324       localtime().
325
326           $lxs->settime('%Y/%m/%d %H:%M:%S');
327
328       To get more information about the formats take a look at "strftime()"
329       of POSIX.pm or the manpage strftime(3).
330
331   gettime()
332       "gettime()" returns a POSIX formatted time stamp, @foo in list and $bar
333       in scalar context.  If the time format isn't set then the default
334       format "%Y-%m-%d %H:%M:%S" will be set automatically. You can also set
335       a time format with "gettime()".
336
337           my $date_time = $lxs->gettime;
338
339       Or
340
341           my ($date, $time) = $lxs->gettime();
342
343       Or
344
345           my ($date, $time) = $lxs->gettime('%Y/%m/%d %H:%M:%S');
346

EXAMPLES

348       A very simple perl script could looks like this:
349
350           use strict;
351           use warnings;
352           use Sys::Statistics::Linux;
353
354           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
355           sleep(1);
356           my $stat = $lxs->get;
357           my $cpu  = $stat->cpustats->{cpu};
358
359           print "Statistics for CpuStats (all)\n";
360           print "  user      $cpu->{user}\n";
361           print "  nice      $cpu->{nice}\n";
362           print "  system    $cpu->{system}\n";
363           print "  idle      $cpu->{idle}\n";
364           print "  ioWait    $cpu->{iowait}\n";
365           print "  total     $cpu->{total}\n";
366
367       Set and get a time stamp:
368
369           use strict;
370           use warnings;
371           use Sys::Statistics::Linux;
372
373           my $lxs = Sys::Statistics::Linux->new();
374           $lxs->settime('%Y/%m/%d %H:%M:%S');
375           print $lxs->gettime, "\n";
376
377       If you want to know how the data structure looks like you can use
378       "Data::Dumper" to check it:
379
380           use strict;
381           use warnings;
382           use Sys::Statistics::Linux;
383           use Data::Dumper;
384
385           my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
386           sleep(1);
387           my $stat = $lxs->get;
388
389           print Dumper($stat);
390
391       How to get the top 5 processes with the highest cpu workload:
392
393           use strict;
394           use warnings;
395           use Sys::Statistics::Linux;
396
397           my $lxs = Sys::Statistics::Linux->new( processes => 1 );
398           sleep(1);
399           my $stat = $lxs->get;
400           my @top5 = $stat->pstop( ttime => 5 );
401

BACKWARD COMPATIBILITY

403       The old options and keys - CpuStats, NetStats, etc - are still
404       available but deprecated!  It's not possible to access the statistics
405       via Sys::Statistics::Linux::Compilation and it's not possible to call
406       "search()" and "psfind()" if you use the old options.
407
408       You should use the new options and access the statistics over the
409       accessors
410
411           $stats->cpustats
412
413       or directly with
414
415           $stats->{cpustats}
416

PREREQUISITES

418           Carp
419           POSIX
420           Test::More
421           Time::HiRes
422           UNIVERSAL
423

EXPORTS

425       No exports.
426

TODOS

428          * Are there any wishs from your side? Send me a mail!
429

REPORTING BUGS

431       Please report all bugs to <jschulz.cpan(at)bloonix.de>.
432

AUTHOR

434       Jonny Schulz <jschulz.cpan(at)bloonix.de>.
435
437       Copyright (C) 2006-2008 by Jonny Schulz. All rights reserved.
438
439       This program is free software; you can redistribute it and/or modify it
440       under the same terms as Perl itself.
441
442
443
444perl v5.12.2                      2010-12-14         Sys::Statistics::Linux(3)
Impressum