package.json

{
  "name": "libdtrace",
  "version": "0.0.3",
  "description": "Solaris libdtrace bindings",
  "homepage": "https://github.com/bcantrill/node-libdtrace",
  "author": {
    "name": "Joyent",
    "url": "joyent.com"
  },
  "engines": {
    "node": ">=0.8"
  },
  "main": "./index.js",
  "dependencies": {
    "bindings": "1.0.0"
  },
  "scripts": {
    "install": "node-gyp rebuild"
  },
  "gypfile": true,
  "readme": "\nnode-libdtrace\n==============\n\nOverview\n--------\n\nnode-libdtrace is a Node.js addon that interfaces to libdtrace, allowing\nnode programs to control DTrace enablings.\n\nStatus\n------\n\nThe primary objective is not to create a `dtrace(1M)` alternative in node, but\nrather to allow node programs to create and control programmatically useful\nDTrace enablings.  That is, the goal is software-software interaction, and as\nsuch, DTrace actions related to controlling output (e.g., `printf()`,\n`printa()`) are not supported.  Error handling is, for the moment, weak.\n\nPlatforms\n---------\n\nThis should work on any platform that supports DTrace, and is known to work on\nMac OS X (tested on 10.7.5) and illumos (tested on\nSmartOS).\n\nInstallation\n------------\n\nAs an addon, node-libdtrace is installed in the usual way:\n\n      % npm install libdtrace\n\nAPI\n---\n\n### `new libdtrace.Consumer()`\n\nCreate a new libdtrace consumer, which will correspond to a new `libdtrace`\nstate.  If DTrace cannot be initalized for any reason, this will throw an\nexception with the `message` member set to the more detailed reason from\nlibdtrace.  Note that one particularly common failure mode is attempting to\ninitialize DTrace without the necessary level of privilege; in this case, for\nexample, the `message` member will be:\n\n      DTrace requires additional privileges\n\n(The specifics of this particular message should obviously not be \nprogrammatically depended upon.)  If encountering this error, you will\nneed to be a user that has DTrace privileges.\n\n### `consumer.strcompile(str)`\n\nCompile the specified `str` as a D program.  This is required before\nany call to `consumer.go()`.\n\n### `consumer.go()`\n\nInstruments the system using the specified enabling.  Before `consumer.go()`\nis called, the specified D program has been compiled but not executed; once\n`consumer.go()` is called, no further D compilation is possible.\n\n### `consumer.setopt(option, value)`\n\nSets the specified `option` (a string) to `value` (an integer, boolean,\nstring, or string representation of an integer or boolean, as denoted by\nthe option being set).\n\n### `consumer.consume(function func (probe, rec) {})`\n\nConsume any DTrace data traced to the principal buffer since the last call to\n`consumer.consume()` (or the call to `consumer.go()` if `consumer.consume()`\nhas not been called).  For each trace record, `func` will be called and\npassed two arguments:\n\n* `probe` is an object that specifies the probe that corresponds to the\n   trace record in terms of the probe tuple: provider, module, function\n   and name.\n\n* `rec` is an object that has a single member, `data`, that corresponds to\n   the datum within the trace record.  If the trace record has been entirely\n   consumed, `rec` will be `undefined`.\n\nIn terms of implementation, a call to `consumer.consume()` will result in a\ncall to `dtrace_status()` and a principal buffer switch.  Note that if the\nrate of consumption exceeds the specified `switchrate` (set via either\n`#pragma D option switchrate` or `consumer.setopt()`), this will result in no\nnew data processing.\n\n### `consumer.aggwalk(function func (varid, key, value) {})`\n\nSnapshot and iterate over all aggregation data accumulated since the\nlast call to `consumer.aggwalk()` (or the call to `consumer.go()` if\n`consumer.aggwalk()` has not been called).  For each aggregate record,\n`func` will be called and passed three arguments:\n\n* `varid` is the identifier of the aggregation variable.  These IDs are\n  assigned in program order, starting with 1.\n\n* `key` is an array of keys that, taken with the variable identifier,\n  uniquely specifies the aggregation record.\n\n* `value` is the value of the aggregation record, the meaning of which\n  depends on the aggregating action:\n\n  * For `count()`, `sum()`, `max()` and `min()`, the value is the\n    integer value of the aggregation action\n\n  * For `avg()`, the value is the numeric value of the aggregating action\n\n  * For `quantize()` and `lquantize()`, the value is an array of 2-tuples\n    denoting ranges and value:  each element consists of a two element array\n    denoting the range (minimum followed by maximum, inclusive) and the\n    value for that range.  \n\nUpon return from `consumer.aggwalk()`, the aggregation data for the specified\nvariable and key(s) is removed.\n\nNote that the rate of `consumer.aggwalk()` actually consumes the aggregation\nbuffer is clamed by the `aggrate` option; if `consumer.aggwalk()` is called\nmore frequently than the specified rate, `consumer.aggwalk()` will not\ninduce any additional data processing.\n\n`consumer.aggwalk()` does not iterate over aggregation data in any guaranteed\norder, and may interleave aggregation variables and/or keys.\n\n### `consumer.version()`\n\nReturns the version string, as returned from `dtrace -V`.\n\nExamples\n--------\n\n### Hello world\n\nThe obligatory \"hello world\":\n\n      var sys = require('sys');\n      var libdtrace = require('libdtrace');\n      var dtp = new libdtrace.Consumer();\n        \n      var prog = 'BEGIN { trace(\"hello world\"); }';\n        \n      dtp.strcompile(prog);\n      dtp.go();\n        \n      dtp.consume(function (probe, rec) {\n              if (rec)\n                      sys.puts(rec.data);\n      });\n\n### Using aggregations\n\nA slightly more sophisticated example showing system calls aggregated and\nsorted by executable name:\n\n      var sys = require('sys');\n      var libdtrace = require('libdtrace');\n      var dtp = new libdtrace.Consumer();\n      \n      var prog = 'syscall:::entry { @[execname] = count(); }'\n      \n      dtp.strcompile(prog);\n      dtp.go();\n      \n      var syscalls = {};\n      var keys = [];\n      \n      var pad = function (val, len)\n      {\n              var rval = '', i, str = val + '';\n      \n              for (i = 0; i < Math.abs(len) - str.length; i++)\n                      rval += ' ';\n      \n              rval = len < 0 ? str + rval : rval + str;\n      \n              return (rval);\n      };\n      \n      setInterval(function () {\n              var i;\n      \n              sys.puts(pad('EXECNAME', -40) + pad('COUNT', -10));\n      \n              dtp.aggwalk(function (id, key, val) {\n                      if (!syscalls.hasOwnProperty(key[0]))\n                      \tkeys.push(key[0]);\n      \n                      syscalls[key[0]] = val;\n              });\n      \n              keys.sort();\n      \n              for (i = 0; i < keys.length; i++) {\n                      sys.puts(pad(keys[i], -40) + pad(syscalls[keys[i]], -10));\n                      syscalls[keys[i]] = 0;\n              }\n      \n              sys.puts('');\n      }, 1000);\n",
  "readmeFilename": "README.md",
  "_id": "libdtrace@0.0.3",
  "dist": {
    "shasum": "1c38d75fa2d52ac140bc076e947e579bdaa0141a",
    "tarball": "http://registry.npmjs.org/libdtrace/-/libdtrace-0.0.3.tgz"
  },
  "_from": "libdtrace@0.0.3",
  "_npmVersion": "1.2.14",
  "_npmUser": {
    "name": "dap",
    "email": "dap@cs.brown.edu"
  },
  "maintainers": [
    {
      "name": "tjholowaychuk",
      "email": "tj@vision-media.ca"
    },
    {
      "name": "dap",
      "email": "dap@cs.brown.edu"
    }
  ],
  "directories": {},
  "_shasum": "1c38d75fa2d52ac140bc076e947e579bdaa0141a",
  "_resolved": "http://registry.npmjs.org/libdtrace/-/libdtrace-0.0.3.tgz"
}