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

EXAMPLES

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

BACKWARD COMPATIBILITY

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

PREREQUISITES

416           Carp
417           POSIX
418           Test::More
419           Time::HiRes
420           UNIVERSAL
421

EXPORTS

423       No exports.
424

TODOS

426          * Are there any wishs from your side? Send me a mail!
427

REPORTING BUGS

429       Please report all bugs to <jschulz.cpan(at)bloonix.de>.
430

AUTHOR

432       Jonny Schulz <jschulz.cpan(at)bloonix.de>.
433
435       Copyright (C) 2006-2008 by Jonny Schulz. All rights reserved.
436
437       This program is free software; you can redistribute it and/or modify it
438       under the same terms as Perl itself.
439
440
441
442perl v5.38.0                      2023-07-21       Sys::Statistics::Linux(3pm)
Impressum