NAME
Proc::Stat
SYNOPSIS
use Proc::Stat;
my $ps = new Proc::Stat;
my $psj = $ut->jiffy();
my $ut = $ps->uptime();
my $stat = $ps->stat($pid0,$pid1,$pid...);
my $usage = $ut->usage($pid0,$pid1,$pid...);
my $prep = $ps->prepare($pid0,$pid1,...);
my $percent = $prep->loadavg($pid0,$pid1,...);
my $percent = $ps->loadkid($pid0,$pid1,...);DESCRIPTION
This module reads /proc/uptime and /proc/{pid}/stat to gather statistics and calculate cpu utilization of designatated PID's with or without children
All the data from /proc/[pid]/stat is returned attached to the method pointer, see list below by index (-1).
Calculates processor JIFFY
Calculate realtime load average of a particular job(pid) or list of job(pid's)
Real load Balancing using $ps->loadavg(pid list) below.
$ref = new Proc::Stat;
Return a method pointer
$psj = $ut->jiffy();
Returns a blessed reference with a scalar representing the best guess of the SC_CLK_TCK or USR_HZ for this system based on proc data
input: [optional] method pointer from "uptime" returns: $psj->{ jiffy => number };Returns 9999 on error and sets $@
Will call $ps->uptime() if not a $ut->method pointer
NOTE: known to be supported on LINUX, requires the /proc/filesystem
$ut = $ps->uptime();
input: none returns: blessed method pointer of the form $ut->{ # seconds and fractions current => { uptime => uptime of the system, idle => time spent in idle }, last => { uptime => 0, idle => 0, } };Subsequent calls will return:
$ut->{ # seconds and fractions current => { uptime => uptime of the system, idle => time spent in idle }, last => { uptime => previous uptime, idle => previous idle } };Returns undef on error
= $stat = $ps->stat($pid0,$pid1,...);
Returns pointer to an array of values for each proc/PID/stat as defined in man proc(5)
input: an array of PID's or ref to array of PID's returns: blessed method pointer of the form $stat->{ curstat => { $pid0 => [stat array], $pid1 => [stat array], ... }, lastat => { $pid0 => [], $pid1 => [], ... } };Subsequent calls will return:
$stat->{ curstat => { $pid0 => [stat array], $pid1 => [stat array], ... }, lastat => { $pid0 => [], $pid1 => [], ... } };Returns undef on error.
Will not populate PID's missing from /proc
May be chained. i.e.
$stat = $ps->uptime()->stat($pid,...);$usage = $ut->usage();
Calculate the CPU usage from data in a chained uptime, stat call pair
i.e $usage = $ps->uptime()->jiffy()->stats(pid0,pid1,...)->usage(); in any order, only "stats" required
calculates differences for utime stime cutime cstimeFirst call for a particular PID will return the absolute value since job start
Subsequent calls for a particular PID will return the difference from the last call
input: an array of PID's or ref to array of PID's returns: additional fields added to "uptime" and "stats" $usage->{ utime => { $pid0 => diff, $pid1 => diff, ... etc... }, stime => { $pid0 => diff, $pid1 => diff, ... etc... }, cutime => { $pid0 => diff, $pid1 => diff, ... etc... }, cstime => { $pid0 => diff, $pid1 => diff, ... etc... } };Returns undef on error
$prep = $ps->prepare($pid0,$pid1,...);
Collect information about jobs(pids) needed to calculate cpu utilization. Call repetitively at intervals.
input: an array of PID's or ref to array of PID's returns: a blessed hash structure containing dataThis is a wrapper around:
$ps->uptime()->stat($pids);...and will conditionally call ->jiffy if it is not populated
$percent = $prep->loadavg($pid0,$pid1,...);
$percent = $prep->loadkid($pid0,$pid1,...);
Call:
method: loadavg for job(pid) utilization method: loadkid to include utilization of child processesCalculates the % CPU utilization of each job (pid) over the period between calls
input: an array of PID's or ref to array of PID's returns: a blessed hash structure of the form: $ps = { utilize => { $pid0 => num[float 0..100] representing %, $pid1 => num..., ... }, };Method will report ZERO for a job(pid) which does not have a previous call entry.
Return undef on error.
Will call the other package methods as needed to populate the '$ps' hash.
$ps = $ps->purgemissing($pid0,$pid1,...);
Removes all PID's from the '$ps' structure not in the PID list
input: an array of PID's or ref to array of PID's returns: bless reference stripped of all other PID'sReturns undef on error
Contents of /proc/[pid]/stat from proc(5)
pid %d
(1) The process ID.
comm %s
(2) The filename of the executable, in parentheses. This is visible whether or not the executable is swapped out.
state %c
(3) One character from the string "RSDZTW" where R is running, S is sleeping in an interruptible wait, D is waiting in uninterruptible disk sleep, Z is zombie, T is traced or stopped (on a signal), and W is paging.
ppid %d
(4) The PID of the parent.
pgrp %d
(5) The process group ID of the process.
session %d
(6) The session ID of the process.
tty_nr %d
(7) The controlling terminal of the process. (The minor device number is contained in the combination of bits 31 to 20 and 7 to 0; the major device number is in bits 15 to 8.)
tpgid %d
(8) The ID of the foreground process group of the controlling terminal of the process.
flags %u (%lu before Linux 2.6.22)
(9) The kernel flags word of the process. For bit meanings, see the PF_* defines in the Linux kernel source file include/linux/sched.h. Details depend on the kernel version.
minflt %lu
(10) The number of minor faults the process has made which have not required loading a memory page from disk.
cminflt %lu
(11) The number of minor faults that the process's waited-for children have made.
majflt %lu
(12) The number of major faults the process has made which have required loading a memory page from disk.
cmajflt %lu
(13) The number of major faults that the process's waited-for children have made.
utime %lu
(14) Amount of time that this process has been scheduled in user mode, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)). This includes guest time, guest_time (time spent running a virtual CPU, see below), so that applications that are not aware of the guest time field do not lose that time from their calculations.
stime %lu
(15) Amount of time that this process has been scheduled in kernel mode, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)).
cutime %ld
(16) Amount of time that this process's waited-for children have been scheduled in user mode, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)). (See also times(2).) This includes guest time, cguest_time (time spent running a virtual CPU, see below).
cstime %ld
(17) Amount of time that this process's waited-for children have been scheduled in kernel mode, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)).
priority %ld
(18) (Explanation for Linux 2.6) For processes running a real-time scheduling policy (policy below; see sched_setscheduler(2)), this is the negated scheduling priority, minus one; that is, a number in the range -2 to -100, corresponding to real-time priorities 1 to 99. For processes running under a non-real-time scheduling policy, this is the raw nice value (setpriority(2)) as represented in the kernel. The kernel stores nice values as numbers in the range 0 (high) to 39 (low), corresponding to the user-visible nice range of -20 to 19.
Before Linux 2.6, this was a scaled value based on the scheduler weighting given to this process.
nice %ld
(19) The nice value (see setpriority(2)), a value in the range 19 (low priority) to -20 (high priority).
num_threads %ld
(20) Number of threads in this process (since Linux 2.6). Before kernel 2.6, this field was hard coded to 0 as a placeholder for an earlier removed field.
itrealvalue %ld
(21) The time in jiffies before the next SIGALRM is sent to the process due to an interval timer. Since kernel 2.6.17, this field is no longer maintained, and is hard coded as 0.
starttime %llu (was %lu before Linux 2.6)
(22) The time the process started after system boot. In kernels before Linux 2.6, this value was expressed in jiffies. Since Linux 2.6, the value is expressed in clock ticks (divide by sysconf(_SC_CLK_TCK)).
vsize %lu
(23) Virtual memory size in bytes.
rss %ld
(24) Resident Set Size: number of pages the process has in real memory. This is just the pages which count toward text, data, or stack space. This does not include pages which have not been demand-loaded in, or which are swapped out.
rsslim %lu
(25) Current soft limit in bytes on the rss of the process; see the description of RLIMIT_RSS in getrlimit(2).
startcode %lu
(26) The address above which program text can run.
endcode %lu
(27) The address below which program text can run.
startstack %lu
(28) The address of the start (i.e., bottom) of the stack.
kstkesp %lu
(29) The current value of ESP (stack pointer), as found in the kernel stack page for the process.
kstkeip %lu
(30) The current EIP (instruction pointer).
signal %lu
(31) The bitmap of pending signals, displayed as a decimal number. Obsolete, because it does not provide information on real-time signals; use /proc/[pid]/status instead.
blocked %lu
(32) The bitmap of blocked signals, displayed as a decimal number. Obsolete, because it does not provide information on real-time signals; use /proc/[pid]/status instead.
sigignore %lu
(33) The bitmap of ignored signals, displayed as a decimal number. Obsolete, because it does not provide information on real-time signals; use /proc/[pid]/status instead.
sigcatch %lu
(34) The bitmap of caught signals, displayed as a decimal number. Obsolete, because it does not provide information on real-time signals; use /proc/[pid]/status instead.
wchan %lu
(35) This is the "channel" in which the process is waiting. It is the address of a system call, and can be looked up in a namelist if you need a textual name. (If you have an up-to-date /etc/psdatabase, then try ps -l to see the WCHAN field in action.)
nswap %lu
(36) Number of pages swapped (not maintained).
cnswap %lu
(37) Cumulative nswap for child processes (not maintained).
exit_signal %d (since Linux 2.1.22)
(38) Signal to be sent to parent when we die.
processor %d (since Linux 2.2.8)
(39) CPU number last executed on.
rt_priority %u (since Linux 2.5.19; was %lu before Linux 2.6.22)
(40) Real-time scheduling priority, a number in the range 1 to 99 for processes scheduled under a real-time policy, or 0, for non-real-time processes (see sched_setscheduler(2)).
policy %u (since Linux 2.5.19; was %lu before Linux 2.6.22)
(41) Scheduling policy (see sched_setscheduler(2)). Decode using the SCHED_* constants in linux/sched.h.
delayacct_blkio_ticks %llu (since Linux 2.6.18)
(42) Aggregated block I/O delays, measured in clock ticks (centiseconds).
guest_time %lu (since Linux 2.6.24)
(43) Guest time of the process (time spent running a virtual CPU for a guest operating system), measured in clock ticks (divide by sysconf(_SC_CLK_TCK)).
cguest_time %ld (since Linux 2.6.24)
(44) Guest time of the process's children, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)).
BUGS
none so far
COPYRIGHT 2019
Michael Robinton <michael@bizsystems.com>
All rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of either:
a) the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any
later version, or
b) the "Artistic License" which comes with this distribution.This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.
You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one.
You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the
Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301 USA.or visit their web page on the internet at:
http://www.gnu.org/copyleft/gpl.html.AUTHOR
Michael Robinton <michael@bizsystems.com>