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)