README

kstat, a node.js addon for reading kstats
-----------------------------------------

This is a simple node.js addon that allows one to read kernel statistics via
the kstat framework on Solaris.  The "kstat" module exports a single class,
"Reader" that has the following methods:

 Reader():  Takes an optional object specifying the kstats to read.  This
            object may have the following members:

            class    =>  optional string denoting class of kstat(s) to read
            module   =>  optional string denoting module of kstat(s) to read
            name     =>  optional string denoting name of kstat(s) to read
            instance =>  optional integer denoting instance of kstat(s) to read

            Together, these members form a specification of kstats to read.

 read():    Returns an array of kstats that match the specification with
            which the reader instance was constructed.  Each element of the
            array is an object that contains the following members:
            
            class    =>  string denoting class of kstat
            module   =>  string denoting module of kstat
            name     =>  string denoting name of kstat
            instance =>  integer denoting instance of kstat
            snaptime =>  nanoseconds since boot of this snapshot
            crtime   =>  nanoseconds since boot that this kstat was created
            type     =>  integer representing the internal type of kstat
            data     =>  an object containing the named kstat data itself

 list():    Returns the list of all kstats. Each entry is as above, but
            without the data, so the potentially expensive step of reading
            the kstat data is omitted.

 getkcid(): Returns, as an int, the current ID of the kstat chain.

 chainupdate(): Update the kstat chain and return 0 if unchanged or the new
            chain ID if the chain changed.

For example, here is a simple node.js program that dumps the kstats of
class 'mib2':

  var kstat = require('kstat');
  var sys = require('sys');
  var reader = new kstat.Reader({ 'class': 'mib2' } );
  sys.puts(sys.inspect(reader.read()));

Here is a the same program that reads only the 'mib2' class kstats from
the 'icmp' module:

  var kstat = require('kstat');
  var sys = require('sys');
  var reader = new kstat.Reader({ 'class': 'mib2', module: 'icmp' } );
  sys.puts(sys.inspect(reader.read()));

Finally, here is a simple program that prints the number of ICMP datagrams
received per second:

  var kstat = require('kstat');
  var sys = require('sys');
  var reader = new kstat.Reader({ 'class': 'mib2', module: 'icmp' } );

  var data = [];
  var gen = 0;

  setInterval(function() {
        data[gen] = reader.read()[0];
        gen ^= 1;

        if (!(data[0] && data[1]))
                return;

          sys.puts(data[gen ^ 1].data.inDatagrams - data[gen].data.inDatagrams);
  }, 1000);