KSTAT(3PERL) Perl Library Functions KSTAT(3PERL)
NAME
Kstat - Perl tied hash interface to the kstat facility
SYNOPSIS
use Sun::Solaris::Kstat;
Sun::Solaris::Kstat->new();
Sun::Solaris::Kstat->update();
Sun::Solaris::Kstat->{module}{instance}{name}{statistic}
DESCRIPTION
Kernel statistics are categorized using a 3-part key consisting of
the module, the instance, and the statistic name. For example, CPU
information can be found under
cpu_stat:0:cpu_stat0, as in the above
example. The method
Sun::Solaris::Kstat->
new() creates a new 3-layer
tree of Perl hashes with the same structure; that is, the statistic
for CPU 0 can be accessed as
$ks->{cpu_stat}{0}{cpu_stat0}. The
fourth and lowest layer is a tied hash used to hold the individual
statistics values for a particular system resource.
For performance reasons, the creation of a
Sun::Solaris::Kstat object
is not accompanied by a following read of all possible statistics.
Instead, the 3-layer structure described above is created, but reads
of a statistic's values are done only when referenced. For example,
accessing
$ks->{cpu_stat}{0}{cpu_stat0}{syscall} will read in all the
statistics for CPU 0, including user, system, and wait times, and the
other CPU statistics, as well as the number of system call entries.
Once you have accessed a lowest level statistics value, calling
$ks->
update() will automatically update all the individual values of
any statistics you have accessed.
There are two values of the lowest-level hash that can be read
without causing the full set of statistics to be read from the
kernel. These are "class", which is the
kstat class of the
statistics, and "crtime"n, which is the time that the kstat was
created. See
kstat(3KSTAT) for full details of these fields.
Methods
new() Create a new kstat statistics hierarchy and return a
reference to the top-level hash. Use it like any normal
hash to access the statistics.
update() Update all the statistics that have been accessed so far.
In scalar context,
update() returns 1 if the
kstat structure has changed, and 0 otherwise. In list context,
update() returns references to two arrays: the first
holds the keys of any kstats that have been added, and
the second holds the keys of any kstats that have been
deleted. Each key will be returned in the form
"
module:
instance:
name".
EXAMPLES
Example 1: Sun::Solaris::Kstat example
use Sun::Solaris::Kstat;
my $kstat = Sun::Solaris::Kstat->new();
my ($usr1, $sys1, $wio1, $idle1) =
@{$kstat->{cpu_stat}{0}{cpu_stat0}}{qw(user kernel
wait idle)};
print("usr sys wio idle\n");
while (1) {
sleep 5;
if ($kstat->update()) {
print("Configuration changed\n");
}
my ($usr2, $sys2, $wio2, $idle2) =
@{$kstat->{cpu_stat}{0}{cpu_stat0}}{qw(user kernel
wait idle)};
printf(" %.2d %.2d %.2d %.2d\n",
($usr2 - $usr1) / 5, ($sys2 - $sys1) / 5,
($wio2 - $wio1) / 5, ($idle2 - $idle1) / 5);
$usr1 = $usr2;
$sys1 = $sys2;
$wio1 = $wio2;
$idle1 = $idle2;
}
SEE ALSO
perl(1),
kstat(3KSTAT),
kstat_chain_update(3KSTAT),
kstat_close(3KSTAT),
kstat_open(3KSTAT),
kstat_read(3KSTAT),
kstat(8)NOTES
As the statistics are stored in a tied hash, taking additional
references of members of the hash, such as
my $ref = \ks->{cpu_stat}{0}{cpu_stat0}{syscall};
print("$$ref\n");
will be recorded as a hold on that statistic's value, preventing it
from being updated by
refresh(). Copy the values explicitly if
persistence is necessary.
Several of the statistics provided by the
kstat facility are stored
as 64-bit integer values. Perl 5 does not yet internally support
64-bit integers, so these values are approximated in this module.
There are two classes of 64-bit value to be dealt with:
64-bit intervals and times These are the
crtime and
snaptime fields of all the statistics hashes,
and the
wtime,
wlentime,
wlastupdate,
rtime,
rlentime and
rlastupdate fields
of the
kstat I/O statistics structures.
These are measured by the
kstat facility in nanoseconds, meaning that a
32-bit value would represent
approximately 4 seconds. The
alternative is to store the values as
floating-point numbers, which offer
approximately 53 bits of precision on
present hardware. 64-bit intervals and
timers as floating point values
expressed in seconds, meaning that
time-related kstats are being rounded
to approximately microsecond
resolution.
64-bit counters It is not useful to store these values
as 32-bit values. As noted above,
floating-point values offer 53 bits of
precision. Accordingly, all 64-bit
counters are stored as floating-point
values.
July 21, 2005 KSTAT(3PERL)
