probe-trace

Stability: 1 - Experimental

Instrument code with probes.

Installation

npm install probe-trace

Tests

npm test

Benchmarks

npm run-script benchmark

Overview

probe-trace enables instrumenting live Node.js code using probes using only JavaScript.

It is sometimes useful to instrument live code in order to find out what's going on. In such cases, for code designed to support it, one could open a REPL to a running Node.js process, add instrumentation, and turn on various probes.

Example

We will use the Node.js REPL to illustrate instrumenting live code. For this purpose we will use examples/hello.js module as an example. The module is an HTTP server that returns "hello world" via calling a hello() and a world() function to construct the response.

node
> var Hello = require('./examples/hello.js');
undefined
> var hello = new Hello();
undefined
> hello.listen(8080, function () { console.log('listening on 8080...'); });
undefined
> listening on 8080...

At this point, you can curl localhost:8080 to see that the server is up.

We will now attach a probe to the

> var Probe = require('./index.js');
undefined
> var probe = new Probe();
undefined
> Hello.prototype.hello = probe.instrument('hello', Hello.prototype.hello);
{ [Function] _original: [Function: hello] }

You can now curl localhost:8080 and see that it still works.

We will dump the entry event to the console.

> probe.on('~probe:hello:enter', function (event) { console.dir(event); });
{ activeProbes: {},
  _events: { '~probe:hello:enter': [Function] } }
> probe.addProbe('hello');
undefined

Now, when you curl localhost:8080 you'll see output in the console:

> { name: 'hello',
  context: undefined,
  timestamp: 1380487865677,
  args: [] }

To turn off the probe again

> probe.removeProbe('hello');
undefined

Now, curl localhost:8080 will not log anymore.

To return the server to original state:

> Hello.prototype.hello = probe.uninstrument(Hello.prototype.hello);

curl localhost:8080 continues to work.

Performance

Instrumenting functions has its performance penalty, hence it is useful to uninstrument() when no longer needed.

The current performance benchmark gives intuition as to the cost of probe-trace instrumentation:

Starting benchmark...
Running uninstrumented...
Running instrumented but off...
Running instrumented and on...
Running instrumented, on, and with listeners registered...
Benchmark results:
  uninstrumented time                    :     7655464ns  130625655 calls/sec
  instrumented but off time              :   154998699ns    6451667 calls/sec
  instrumented and on time               :  4746867607ns     210665 calls/sec
  instrumented and on with listeners time:  5128034667ns     195006 calls/sec

Documentation

Probe

Public API

• new Probe()
• probe.addProbe(name)
• probe.instrument(name, func)
• probe.removeProbe(name)
• probe.uninstrument(func)
• Event '~probe::enter'
• Event '~probe::error'
• Event '~probe::return'

new Probe()

Creates a new Probe instance.

probe.addProbe(name)

• name: String Name of a probe to turn on.

Turns on a probe for previously instrumented function.

probe.instrument(name, func)

• name: String Name of the probe.
• func: Function Function to instrument.
• Return: Function Instrumented function.

Instruments a function for probing and relates it to the name.

probe.removeProbe(name)

• name: String Name of a probe to turn off.

Turns off a previously turned on probe for a function.

probe.uninstrument(func)

• func: Function Previously instrumented function.
• Return: Function Uninstrumented function.

If the func has not been previously instrumented, it is simply returned.

Event ~probe:<name>:enter

• event: Object
  • name: String Name of the probe.
  • context: Object Reserved for future use.
  • timestamp: Integer Result of new Date().getTime().
  • args: Array Arguments passed to the instrumented function.

Emitted upon entry into an instrumented function for which the probe is on.

Event ~probe:<name>:error

• event: Object
  • name: String Name of the probe.
  • context: Object Reserved for future use.
  • timestamp: Integer Result of new Date().getTime().
  • duration: Integer Instrumented function duration in nanoseconds.
  • args: Array Arguments passed to the instrumented function.
  • error: Any Any exception thrown by the instrumented function.

Emitted if an instrumented function, for which the probe is on, throws. After the event is emitted, the throw is propagated.

Event ~probe:<name>:return

• event: Object
  • name: String Name of the probe.
  • context: Object Reserved for future use.
  • timestamp: Integer Result of new Date().getTime().
  • duration: Integer Instrumented function duration in nanoseconds.
  • args: Array Arguments passed to the instrumented function.
  • result: Any Any result returned by the instrumented function.

Emitted upon return from an instrumented function for which the probe is on.