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 the man proc(5) entry elsewhere in this document
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
cstime
First 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 data
This 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 processes
Calculates 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's
Returns 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 <
[email protected]>
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 <
[email protected]>
