Sys::S...:Linux(3pm)

📦
version 0.66 · 6 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Sys::S...:Linux(3pm) 💖

okay bestie, so this is a page from the User Contributed Perl Documentation — it's Sys::S...:Linux(3pm), and it's literally your girl's whole personality. no cap. let's get into it ✨

✨ NAME ✨

Sys::Statistics::Linux — the front-end module to collect system statistics 🫶

🌸 SYNOPSIS 🌸

okay so here's the vibe, right:

use Sys::Statistics::Linux;

my $lxs = Sys::Statistics::Linux->new(
    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;

periodt. that's the whole first move 💅

🦋 DESCRIPTION 🦋

Sys::Statistics::Linux is a front-end module, and it gathers all the different linux system info you could possibly want — processor workload, memory usage, network stats, disk stats, and honestly a lot more. if you wanna know about every possible statistic, go read the docs of the distribution modules, because they're the ones doing the actual heavy lifting. 👑

🎀 MOTIVATION 🎀

ngl the author's motivation is super simple. every linux admin out there knows the iconic tool sar from sysstat — it helps so much when you're hunting down system bottlenecks and solving problems, but the way that it's hard to parse the output if you want to store your statistics into a database?? yeah, no. so the author was like "let me develop Sys::Statistics::Linux". it's not a replacement, bestie — it just makes it simpler for you to write your own system monitor. ✨

and fr fr, if Sys::Statistics::Linux doesn't provide statistics that are strongly needed, just let the author know. 💌

🌈 TECHNICAL NOTE 🌈

so this distribution collects its statistics through the virtual /proc filesystem (procfs) and it's developed on the default vanilla kernel. it's been tested on x86 hardware with these distributions — RHEL, Fedora, Debian, Ubuntu, Asianux, Slackware, Mandriva and openSuSE (SLES on zSeries as well, but a long time ago, lowkey ancient history 😭) — on kernel versions 2.4 and/or 2.6.

⚠️ it's possible that it doesn't run on all linux distributions if some procfs features are deactivated or too much modified. for example, the linux kernel 2.4 can be compiled with the option CONFIG_BLK_STATS, which turns block statistics for devices on or off.

and listen — don't give up if some of the modules don't run on your hardware! tell the author what's wrong and they'll try to solve it! you just have to make the first move and send a mail. :-) 🫶

💜 VIRTUAL MACHINES 💜

heads up bestie — if you try to install or run Sys::Statistics::Linux under virtual machines on guest systems, some statistics are not available, such as SockStats, PgSwStats and DiskStats. the reason is that not all /proc data are passed to the guests. it's giving incomplete data, iykyk. 💀

if the installation fails, then try to force the installation with:

cpan> force install Sys::Statistics::Linux

and notice which tests fail, because those statistics maybe aren't available on the virtual machine — sorry. 🙈

🍓 DELTAS 🍓

okay this part is important so lock in 🔥

the statistics for CpuStats, ProcStats, PgSwStats, NetStats, DiskStats and Processes are deltas. for this reason it's necessary to initialize the statistics before the data can be prepared by get(). these statistics can be initialized with the methods new(), set() and init().

for any option that is set to 1, the statistics will be initialized by the call of new() or set(). the call of init() re-initializes all statistics that are set to 1 or 2. by the call of get() the initial statistics will be updated automatically. please refer the section METHODS to get more information about the usage of new(), set(), init() and get(). 📚

another exigence is to sleep for a while — at least for one second — before the call of get() if you want to get useful statistics. 😴

the statistics for SysInfo, MemStats, SockStats, DiskUsage, LoadAVG and FileStats are no deltas. so if you need only one of these, you don't need to sleep before the call of get(). slay, no waiting around. ✨

the method get() prepares all requested statistics and returns the statistics as a Sys::Statistics::Linux::Compilation object. the initial statistics will be updated. 💅

👑 MANUAL PROC(5) 👑

The Linux Programmer's Manual 🌸

http://www.kernel.org/doc/man-pages/online/pages/man5/proc.5.html

if you have questions or you don't understand the sense of some statistics, then take a look into this awesome documentation. it's literally so good. 🔥

💅 OPTIONS 💅

all options are identical with the package names of the distribution in lowercase. to activate the gathering of statistics you have to set the options by the call of new() or set(). in addition you can deactivate statistics with set(). ✨

the options must be set with one of the following values:

0 - deactivate statistics
1 - activate and init statistics
2 - activate statistics but don't init

in addition it's possible to pass a hash reference with options. 🫶

my $lxs = Sys::Statistics::Linux->new(
    processes => {
        init => 1,
        pids => [ 1, 2, 3 ]
    },
    netstats => {
        init => 1,
        initfile => $file,
    },
);

option initfile is useful if you want to store initial statistics on the filesystem. 💾

my $lxs = Sys::Statistics::Linux->new(
    cpustats => {
        init     => 1,
        initfile => '/tmp/cpustats.yml',
    },
    diskstats => {
        init     => 1,
        initfile => '/tmp/diskstats.yml',
    },
    netstats => {
        init     => 1,
        initfile => '/tmp/netstats.yml',
    },
    pgswstats => {
        init     => 1,
        initfile => '/tmp/pgswstats.yml',
    },
    procstats => {
        init     => 1,
        initfile => '/tmp/procstats.yml',
    },
);

example, bestie:

#!/usr/bin/perl
use strict;
use warnings;
use Sys::Statistics::Linux;

my $lxs = Sys::Statistics::Linux->new(
    pgswstats => {
        init => 1,
        initfile => '/tmp/pgswstats.yml'
    }
);

$lxs->get(); # without to sleep

the initial statistics are stored to the temporary file: 📁

#> cat /tmp/pgswstats.yml
---
pgfault: 397040955
pgmajfault: 4611
pgpgin: 21531693
pgpgout: 49511043
pswpin: 8
pswpout: 272
time: 1236783534.9328

every time you call the script the initial statistics are loaded/stored from/to the file. this could be helpful if you don't run it as a daemon and you want to calculate the average load of your system since the last call. do you understand? i hope so :) 🥹

to get more information about the statistics, refer the different modules of the distribution:

sysinfo     -  Collect system information              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 ✨

okay bestie, this is the part where you actually drive the thing 💅 these are the methods you call on your Sys::Statistics::Linux object, and they're all lowkey iconic. no cap.

✨ new() ✨

Call new() to create a new Sys::Statistics::Linux object. You can call new() with options. Those options get passed to the method set().

Without options

my $lxs = Sys::Statistics::Linux->new();

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);

✨ set() ✨

Call set() to activate or deactivate options.

The following example would call new() and initialize Sys::Statistics::Linux::CpuStats and delete the object of Sys::Statistics::Linux::SysInfo. (yes bestie, that's literally what it says 😭)

$lxs->set(
    processes =>  0, # deactivate this statistic
    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 a Sys::Statistics::Linux::Compilation object.

my $lxs  = Sys::Statistics::Linux->new(\%options);
sleep(1);
my $stat = $lxs->get();

Or you can pass the time to sleep with the call of get(). 😴

my $stat = $lxs->get($time_to_sleep);

Now the statistics are available with

$stat->cpustats

# or

$stat->{cpustats}

Take a look to the documentation of Sys::Statistics::Linux::Compilation for more information. 👑

✨ init() ✨

The call of init() initiates all activated statistics that are necessary for deltas. That could be helpful if your script runs in an endless loop with a high sleep interval. Don't forget that if you call get() that the statistics are deltas since the last time they were initiated. ⚠️

The following example would calculate average statistics for 30 minutes:

# initiate cpustats
my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );

while ( 1 ) {
    sleep(1800);
    my $stat = $lxs->get;
}

If you just want a current snapshot of the system each 30 minutes and not the average then the following example would be better for you:

# do not initiate cpustats
my $lxs = Sys::Statistics::Linux->new( cpustats => 2 );

while ( 1 ) {
    $lxs->init;              # init the statistics
    my $stat = $lxs->get(1); # get the statistics
    sleep(1800);             # sleep until the next run
}

If you want to write a simple command line utility that prints the current workload to the screen then you can use something like this:

my @order = qw(user system iowait idle nice irq softirq total);
printf "%-20s%8s%8s%8s%8s%8s%8s%8s%8s\n", 'time', @order;

my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );

while ( 1 ){
    my $cpu  = $lxs->get(1)->cpustats;
    my $time = $lxs->gettime;
    printf "%-20s%8s%8s%8s%8s%8s%8s%8s%8s\n",
        $time, @{$cpu->{cpu}}{@order};
}

✨ settime() ✨

Call settime() to define a POSIX formatted time stamp, generated with localtime().

$lxs->settime('%Y/%m/%d %H:%M:%S');

To get more information 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 strict;
use warnings;
use Sys::Statistics::Linux;

my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
sleep(1);
my $stat = $lxs->get;
my $cpu  = $stat->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";

Set and get a time stamp:

use strict;
use warnings;
use Sys::Statistics::Linux;

my $lxs = Sys::Statistics::Linux->new();
$lxs->settime('%Y/%m/%d %H:%M:%S');
print $lxs->gettime, "\n";

If you want to know how the data structure looks like you can use Data::Dumper to check it:

use strict;
use warnings;
use Sys::Statistics::Linux;
use Data::Dumper;

my $lxs = Sys::Statistics::Linux->new( cpustats => 1 );
sleep(1);
my $stat = $lxs->get;

print Dumper($stat);

How to get the top 5 processes with the highest cpu workload:

use strict;
use warnings;
use Sys::Statistics::Linux;

my $lxs = Sys::Statistics::Linux->new( processes => 1 );
sleep(1);
my $stat = $lxs->get;
my @top5 = $stat->pstop( ttime => 5 );

✨ BACKWARD COMPATIBILITY ✨

The old options and keys - CpuStats, NetStats, etc - are still available but deprecated! It's not possible to access the statistics via Sys::Statistics::Linux::Compilation and it's not possible to call search() and psfind() if you use the old options. 💀

You should use the new options and access the statistics over the accessors

$stats->cpustats

or directly with

$stats->{cpustats}

✨ PREREQUISITES ✨

  • Carp
  • POSIX
  • Test::More
  • Time::HiRes
  • UNIVERSAL

✨ EXPORTS ✨

No exports.

✨ TODOS ✨

  • Are there any wishs from your side? Send me a mail! 💌

✨ REPORTING BUGS ✨

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

✨ AUTHOR ✨

Jonny Schulz <jschulz.cpan(at)bloonix.de>.

Copyright (C) 2006-2008 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.

That's the whole vibe, bestie — from perl v5.36.0, dated 2022-11-19, in Sys::S...:Linux(3pm). 💖

📦 where this page comes from