NAME

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

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'}};

DESCRIPTION

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

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

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

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

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

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

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

DATA FORMAT

Here is a commented 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'
    ],
  };

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 fetch() samples regularly and divide the counter increments by the time interval between the samples.

The 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 cpu_time increments and the time interval between the samples. Most often you will be interested in the percentage of CPU states only.

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

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 Microsoft Windows clients, talking to rstat servers running on Linux and Solaris.

BUGS AND DESIGN LIMITATIONS

For portability reasons this package uses version 3 (RSTATVERS_TIME) of the rstatd protocol. Version 4 adds dynamically sized arrays for CPU state and disk access but was not available on all targeted plattforms.

As any software this package may contain bugs. Please feel free to contact the author if you find one.

AUTHOR / COPYRIGHT

Version 2.0 and Later, Including This Version

Ron Isaacson <ron.isaacson@morganstanley.com>

Copyright (c) 2008, Morgan Stanley & Co. Incorporated

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2, as published by the Free Software Foundation.

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 the GNU General Public License, version 2 for more details.

A copy of the GNU General Public License was distributed with this program in a file called LICENSE. For additional copies, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

THE FOLLOWING DISCLAIMER APPLIES TO ALL SOFTWARE CODE AND OTHER MATERIALS CONTRIBUTED IN CONNECTION WITH THIS SOFTWARE:

THIS SOFTWARE IS LICENSED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND ANY WARRANTY OF NON-INFRINGEMENT, ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THIS SOFTWARE MAY BE REDISTRIBUTED TO OTHERS ONLY BY EFFECTIVELY USING THIS OR ANOTHER EQUIVALENT DISCLAIMER AS WELL AS ANY OTHER LICENSE TERMS THAT MAY APPLY.

Version 1.2 and Earlier

Axel Schwenke <axel.schwenke@gmx.net>

Copyright (c) 2002 Axel Schwenke. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

Version 2.2 (April 16, 2008)

SEE ALSO

rstatd(8)

cpanm Rstat::Client

perl -MCPAN -e shell
install Rstat::Client