1Sys::Statistics::Linux(U3s)er Contributed Perl DocumentatSiyosn::Statistics::Linux(3)
2
6 Sys::Statistics::Linux - Front-end module to collect system statistics
7
9 use Sys::Statistics::Linux;
10 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 sleep 1;
27 my $stat = $lxs->get;
28
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
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 If Sys::Statistics::Linux doesn't provide statistics that are strongly
45 needed then let me know it.
46
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 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
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 If the installation fails then try to force the installation with
69 cpan> force install Sys::Statistics::Linux
71 and notice which tests fails, because this statistics maybe not
73 available on the virtual machine - sorry.
74
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 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 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
98 The Linux Programmer's Manual
99 http://www.kernel.org/doc/man-pages/online/pages/man5/proc.5.html
101 If you have questions or don't understand the sense of some statistics
103 then take a look into this awesome documentation.
104
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 The options must be set with one of the following values:
112 0 - deactivate statistics
114 1 - activate and init statistics
115 2 - activate statistics but don't init
116 In addition it's possible to pass a hash reference with options.
118 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 Option "initfile" is useful if you want to store initial statistics on
131 the filesystem.
132 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 Example:
157 #!/usr/bin/perl
159 use strict;
160 use warnings;
161 use Sys::Statistics::Linux;
162 my $lxs = Sys::Statistics::Linux->new(
164 pgswstats => {
165 init => 1,
166 initfile => '/tmp/pgswstats.yml'
167 }
168 );
169 $lxs->get(); # without to sleep
171 The initial statistics are stored to the temporary file:
173 #> 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 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 To get more information about the statistics refer the different
190 modules of the distribution.
191 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
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 Without options
212 my $lxs = Sys::Statistics::Linux->new();
214 Or with options
216 my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
218 Would do nothing
220 my $lxs = Sys::Statistics::Linux->new( cpustats => 0 );
222 It's possible to call "new()" with a hash reference of options.
224 my %options = (
226 cpustats => 1,
227 memstats => 1
228 );
229 my $lxs = Sys::Statistics::Linux->new(\%options);
231 set()
233 Call "set()" to activate or deactivate options.
234 The following example would call "new()" and initialize
236 "Sys::Statistics::Linux::CpuStats" and delete the object of
237 "Sys::Statistics::Linux::SysInfo".
238 $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 It's possible to call "set()" with a hash reference of options.
246 my %options = (
248 cpustats => 2,
249 memstats => 2
250 );
251 $lxs->set(\%options);
253 get()
255 Call "get()" to get the collected statistics. "get()" returns a
256 Sys::Statistics::Linux::Compilation object.
257 my $lxs = Sys::Statistics::Linux->new(\%options);
259 sleep(1);
260 my $stat = $lxs->get();
261 Or you can pass the time to sleep with the call of "get()".
263 my $stat = $lxs->get($time_to_sleep);
265 Now the statistcs are available with
267 $stat->cpustats
269 # or
271 $stat->{cpustats}
273 Take a look to the documentation of Sys::Statistics::Linux::Compilation
275 for more information.
276 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 The following example would calculate average statistics for 30
285 minutes:
286 # initiate cpustats
288 my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
289 while ( 1 ) {
291 sleep(1800);
292 my $stat = $lxs->get;
293 }
294 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 # do not initiate cpustats
299 my $lxs = Sys::Statistics::Linux->new( cpustats => 2 );
300 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 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 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 my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
314 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 settime()
323 Call "settime()" to define a POSIX formatted time stamp, generated with
324 localtime().
325 $lxs->settime('%Y/%m/%d %H:%M:%S');
327 To get more information about the formats take a look at "strftime()"
329 of POSIX.pm or the manpage strftime(3).
330 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 my $date_time = $lxs->gettime;
338 Or
340 my ($date, $time) = $lxs->gettime();
342 Or
344 my ($date, $time) = $lxs->gettime('%Y/%m/%d %H:%M:%S');
346
348 A very simple perl script could looks like this:
349 use strict;
351 use warnings;
352 use Sys::Statistics::Linux;
353 my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
355 sleep(1);
356 my $stat = $lxs->get;
357 my $cpu = $stat->cpustats->{cpu};
358 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 Set and get a time stamp:
368 use strict;
370 use warnings;
371 use Sys::Statistics::Linux;
372 my $lxs = Sys::Statistics::Linux->new();
374 $lxs->settime('%Y/%m/%d %H:%M:%S');
375 print $lxs->gettime, "\n";
376 If you want to know how the data structure looks like you can use
378 "Data::Dumper" to check it:
379 use strict;
381 use warnings;
382 use Sys::Statistics::Linux;
383 use Data::Dumper;
384 my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
386 sleep(1);
387 my $stat = $lxs->get;
388 print Dumper($stat);
390 How to get the top 5 processes with the highest cpu workload:
392 use strict;
394 use warnings;
395 use Sys::Statistics::Linux;
396 my $lxs = Sys::Statistics::Linux->new( processes => 1 );
398 sleep(1);
399 my $stat = $lxs->get;
400 my @top5 = $stat->pstop( ttime => 5 );
401
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 You should use the new options and access the statistics over the
409 accessors
410 $stats->cpustats
412 or directly with
414 $stats->{cpustats}
416
418 Carp
419 POSIX
420 Test::More
421 Time::HiRes
422 UNIVERSAL
423
425 No exports.
426
428 * Are there any wishs from your side? Send me a mail!
429
431 Please report all bugs to <jschulz.cpan(at)bloonix.de>.
432
434 Jonny Schulz <jschulz.cpan(at)bloonix.de>.
435
437 Copyright (C) 2006-2008 by Jonny Schulz. All rights reserved.
438 This program is free software; you can redistribute it and/or modify it
440 under the same terms as Perl itself.
441perl v5.12.2 2010-12-14 Sys::Statistics::Linux(3)