Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including dtrace-provider with all npm packages installed. Try it out:

var dtraceProvider = require("dtrace-provider")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

dtrace-provider v0.0.9

Native DTrace providers for node.js applications

dtrace-provider - Native DTrace providers for Node.js apps.

This extension allows you to create native DTrace providers for your Node.js applications. That is, to create providers and probes which expose information specific to your application, rather than information about the node runtime.

You could use this to expose high-level information about the inner workings of your application, or to create a specific context in which to look at information from other runtime or system-level providers.

The provider is not created in the usual way, by declaring it and then changing the build process to include it, but instead dynamically at runtime. This is done entirely in-process, and there is no background compiler or dtrace(1) invocation. The process creating the provider need not run as root.

INSTALL

$ npm install dtrace-provider

EXAMPLE

Here's a simple example of creating a provider:

var d = require('dtrace-provider');

var dtp = d.createDTraceProvider("nodeapp");
dtp.addProbe("probe1", "int", "int");
dtp.addProbe("probe2", "char *");
dtp.enable();      
dtp.fire("probe1", function() { return [1, 2]; });
dtp.fire("probe2", function() { return ["hello, dtrace"]; });

This example creates a provider called "nodeapp", and adds two probes. It then enables the provider, at which point the provider becomes visible to DTrace.

The probes are then fired, which produces this output:

$ sudo dtrace -Z -n 'nodeapp*:::probe1{ trace(arg0); trace(arg1) }'  \
                 -n 'nodeapp*:::probe2{ trace(copyinstr(arg0));  }'
dtrace: description 'nodeapp*:::probe1' matched 0 probes
dtrace: description 'nodeapp*:::probe2' matched 0 probes
CPU     ID                    FUNCTION:NAME
  1 123562                      func:probe1                 1                2
  1 123563                      func:probe2   hello, dtrace                    

Arguments are captured by a callback only executed when the probe is enabled. This means you can do more expensive work to gather arguments.

PLATFORM SUPPORT

The nature of this extension means that support must be added for each platform. Right now that support is only in place for OS X, 64 bit and Solaris, 32 bit.

LIMITATIONS

The maximum number of probe arguments is 6. There's scope to increase this, with some extra complexity in the platform-specific code.

The data types supported are "int" and "char *". There's definitely scope to improve this, with more elaborate argument handling - see TODO.md

You can only create a provider once - although you don't have to do it immediately, once you've set up a provider you can't change its definition. It should be possible to enable updates - again, see TODO.md.

CAVEATS

Performance is not where it should be, most especially the disabled-probe effect. Probes are already using the "is-enabled" feature of DTrace to control execution of the arguments-gathering callback, but too much work needs to be done before that's checked. That being said, unless your (disabled) probes are insanely hot, this shouldn't be a problem.

Please see TODO.md for the details.

CONTRIBUTING

The source is available at:

https://github.com/chrisa/node-dtrace-provider.

For issues, please use the Github issue tracker linked to the repository. Github pull requests are very welcome.

OTHER IMPLEMENTATIONS

This node extension is derived from the ruby-dtrace gem, via the Perl module Devel::DTrace::Provider, both of which provide the same functionality to those languages.

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free