view release on metacpan or  search on metacpan

Client.pm  view on Meta::CPAN

  return $port;

}

#####
#
# Public methods
#
#####

#
# Make the rstat request, with optional timeout
#

sub fetch {

  my ($self, $timeout) = @_;

  my $port = _get_port ($self->{host}, $timeout) or return;
  my $xid  = _make_xid;

  my @request =
    (
     $xid,        # transaction id
     0x00000000,  # request type (CALL)
     0x00000002,  # rpc version
     0x000186a1,  # program (rstat)
     0x00000003,  # version
     0x00000001,  # procedure
     0x00000000,
     0x00000000,
     0x00000000,
     0x00000000
    );

  my $request = pack "N*", @request;
  my $reply   = _udp_request ($self->{host}, $port, $request, $timeout)
    or return;

  my @reply   = unpack "N*", $reply;

  (shift @reply == $xid) or do { $@ = "Transaction id mismatch\n";   return };
  (shift @reply == 0x01) or do { $@ = "Invalid reply\n";             return };
  (shift @reply == 0x00) or do { $@ = "rstat request failed\n";      return };

  shift @reply for (1..3);

  my $stats = {};

  $stats->{'cp_time'}->[0]     = shift @reply;
  $stats->{'cp_time'}->[1]     = shift @reply;
  $stats->{'cp_time'}->[2]     = shift @reply;
  $stats->{'cp_time'}->[3]     = shift @reply;

  $stats->{'dk_xfer'}->[0]     = shift @reply;
  $stats->{'dk_xfer'}->[1]     = shift @reply;
  $stats->{'dk_xfer'}->[2]     = shift @reply;
  $stats->{'dk_xfer'}->[3]     = shift @reply;

  $stats->{'v_pgpgin'}         = shift @reply;
  $stats->{'v_pgpgout'}        = shift @reply;
  $stats->{'v_pswpin'}         = shift @reply;
  $stats->{'v_pswpout'}        = shift @reply;
  $stats->{'v_intr'}           = shift @reply;
  $stats->{'if_ipackets'}      = shift @reply;
  $stats->{'if_ierrors'}       = shift @reply;
  $stats->{'if_oerrors'}       = shift @reply;
  $stats->{'if_collisions'}    = shift @reply;
  $stats->{'v_swtch'}          = shift @reply;

  $stats->{'avenrun'}->[0]     = (shift @reply) / 256;
  $stats->{'avenrun'}->[1]     = (shift @reply) / 256;
  $stats->{'avenrun'}->[2]     = (shift @reply) / 256;

  $stats->{'boottime.tv_sec'}  = shift @reply;
  $stats->{'boottime.tv_usec'} = shift @reply;
  $stats->{'curtime.tv_sec'}   = shift @reply;
  $stats->{'curtime.tv_usec'}  = shift @reply;

  $stats->{'if_opackets'}      = shift @reply;

  return $stats;

}

1;

__END__

=head1 NAME

Rstat::Client - Perl library for client access to rstatd

=head1 SYNOPSIS

  use Rstat::Client;
  
  $clnt  = Rstat::Client->new("some.host")
  
  $stats = $clnt->fetch();    # wait for response
  $stats = $clnt->fetch(10);  # fetch with timeout
  
  printf "CPU Load: %.2f %.2f %.2f\n", @{$stats->{'avenrun'}};

=head1 DESCRIPTION

This Perl library gives you access to rstatd statistics. First create
an C<Rstat::Client> object:

  $clnt = Rstat::Client->new($hostname);

The parameter C<$hostname> is optional and defaults to localhost. The
constructor never fails; a valid C<Rstat::Client> object is always
returned.

Fetch statistic records by calling the C<fetch()> method of the
C<Rstat::Client> object:

  $stats = $clnt->fetch($timeout) or die $@;

The parameter C<$timeout> is optional. By default, the C<fetch()>
method will block until a response is returned.

If the request is successful, C<fetch()> returns a reference to a hash
containing the statistics. In the event of an error, C<fetch()>
returns C<undef>, and C<$@> contains the reason for failure.

=head1 DATA FORMAT

Here is a commented C<Data::Dumper> dump of the stats hash:

  $stats = {
    # time when this record was fetched
    'curtime.tv_sec' => '1021885390',
    'curtime.tv_usec' => 181205,
  
    # time when the system was booted
    'boottime.tv_sec' => '1021781411',
    'boottime.tv_usec' => '0',
  
    # pages swapped in/out
    'v_pswpin' => 1,
    'v_pswpout' => '0',
  
    # pages paged in/out
    'v_pgpgin' => 43155,
    'v_pgpgout' => 64266,
  
    # interrupts and context switches
    'v_intr' => 11150229,
    'v_swtch' => 23174363,
  
    # network statistics (sum over all interfaces)
    'if_ipackets' => 43238686,
    'if_ierrors' => 71633,
    'if_opackets' => '87451',
    'if_oerrors' => '0',
    'if_collisions' => 0,
  
    # run queue length (1/5/15 minutes average)
    'avenrun' => [
      '0.45703125',
      '0.21875',
      '0.13671875'
    ],
  
    # cpu time (in ticks) for USER/NICE/SYS/IDLE
    'cp_time' => [
      261982,
      11,
      450845,
      9685071
    ],
  
    # disk transfers
    'dk_xfer' => [
      47053,
      '0',
      '0',
      '0'
    ],
  };

=head2 NOTES

Timestamps are separated into seconds (standard UNIX time) and
microseconds. The availability of a current timestamp allows proper
calculation of the interval between measurements without worrying
about network latency.

Most values are counters. To get the real numbers you have to
C<fetch()> samples regularly and divide the counter increments
by the time interval between the samples.

The C<cpu_time> array holds the ticks spent in the various CPU states
(averaged over all CPUs). If you know the regular tick rate of the target
system you may calculate the number of CPUs from the sum of C<cpu_time>
increments and the time interval between the samples. Most often you
will be interested in the percentage of CPU states only.

The C<avenrun> array is originally shifted by 8 bits. C<Rstat::Client>
takes care of this and returns floating point values.

=head1 PORTABILITY

As of version 2.0, this library is written in pure Perl and should
work on any platform. It has been tested from Linux, Solaris and