kiraz

__.--~~.,-.__
`~-._.-(`-.__`-.
        \
         \--.
        /#   \
,--.    \    /
|  |,-.  '--' ,--.--.  ,--,--. ,-----.
|     /  |  | |  .--' ' ,-.  | `-.  /
|  \  \  |  | |  |    \ '-'  |  /  `-.
`--'`-- tap into live Node.JS apps -'

Summary

kiraz gives a dynamic insight into your live Node.JS apps. It’s a tracing tool written in JavaScript, for JavaScript.

What kiraz provides is known as “dynamic tracing”:

The goal of dynamic tracing is to enable a rich set of debugging information in live processes, often in production, to help discover the root cause of an issue.

Say What?

kiraz enables “tapping” into your Node.JS apps without needing to install things like dtrace or ktap.

If that rings a bell, skip to the next section. Otherwise, you might want to read about dtrace first.

And while you’re at it, you might like looking into the following tools and technologies too:

• Vantage creates a REPL to observe your running Node.JS app in real time.
• Brendan D. Gregg has excellent blog posts about all things related to dynamic tracing and flame graphs.

Well, Isn’t This the Same as “Debugging”?

Dynamic tracing and debugging are different and complementary tools to help you root cause an issue.

When debugging a live app, you’ll have to restart your app in debug mode. Additionally, most of the time you’ll have to freeze your app at certain breakpoints to investigate the state and context of it. — Having to restart your app makes it hard (if not impossible) to debug production systems. Here’s why:

• Stopping at debug breakpoints will freeze your app, and your users will not be able to use it; so you’ll have to direct the traffic elsewhere. — This is not always possible for production instances.
• To enable debug mode, you’ll have to restart the app; which means you’ll lose valuable state information. Also restarting the app will reset its state, and it will be harder to recreate the exact conditions to reproduce the problem.
• Restarting the app will make your users unhappy if not done carefully (i.e., you’ll need to redirect traffic to a backup instance, wait for existing connections to close — it is a tedious process).

Tracing, on the other hand, enables you to put probes into your running system. You can look at those probes whenever you like. You won’t have to restart your server. Ergo, you won’t need to worry about losing valuable state information. Moreover, you won’t be annoying your users either.

While we are on the topic of debugging, you might want to look at Joyent’s guide on Node.JS debugging; or investigate how the Node.JS debugger works. — You might also want to read about how remote debugging works in Eclipse, how to remotely debug apps using WebStorm, or in how easy it is to debug in the Cloud9 IDE.

Wait A Minute — Isn’t There jstrace For That Already?

kiraz is the immediate successor of jstrace, and aside from a few minor changes, kiraz’s usage is fully compatible with jstrace.

kiraz has been built on top jstrace to provide additional features, flexibility, and configurability.

Is kiraz a dtrace|strace|ktap|etc. Replacement?

Short answer:

No.

At its very core, kiraz is a TCP client/server pubsub program that enables the user to inject and remotely execute tracing code.

Tools like dtrace, however, are kernel-level instrumentation programs.

kiraz operates at a much higher level. — This means it does not give you the spectrum of probes that those kernel-level tools have. Therefore, you’ll need to add your own tracing logic your programs, which is not too much of a deal anyway (see the usage examples section for details).

Can I Use kiraz In Production?

Absolutely!

kiraz will have near-zero impact on the application’s performance when it’s idle, and it will have negligible performance impact when it’s in use. Hence, it’s safe to use it in production.

Note

If you use kiraz in production, and want to provide feedback, please create an issue.

Dependencies

kiraz has been tested to work on Node.JS v.5.x. And it will probably work on other versions of Node.JS too. You’ll need Node.JS and npm to use kiraz.

Supported Operating Systems

Kiraz does not have any OS-specific dependencies; therefore it will probably work on Unix, Solaris, Mac OS, and Windows.

If you have problems running kiraz in your operating system, please create an issue.

How to Install

kiraz has two components:

• A global application that you run on the Communication Node
• And a Node.JS module* that you import into your app

For the former, you’ll need to…

npm install kiraz -g

And for the latter you’ll need to do a…

npm install kiraz --save

in your project folder.

These two commands will be enough to get you started ;).

Usage Examples

Let’s assume you have two virtual containers on the same network. — For the sake of the example let’s say they have the following configuration:

bastion:
     IP: 10.0.0.10
     GW: 10.0.0.1
    SUB: 255.255.255.0

app:
    IP: 10.0.0.11
    GW: 10.0.0.1
   SUB: 255.255.255.0

(i.e., two different containers that are on the same subnet).

Add the following code to the app instance:

// file: server.js

'use strict';

import { trace, start } from 'kiraz';

// opens a socket to the bastion.
start( { host: '10.0.0.10', port: 4322 } );

// polling interval.
const INTERVAL = 467;

setInterval( () => {
    setImmediate( () => {
        let delta = process.hrtime( start );

        trace(
            'eventloop:delay',
            { delta: ( ( delta[ 0 ] * 10e9 +
                delta[ 1 ] )  / ( 10e6 ) ) }
        );

        trace(
            'memory:usage',
            { percent: process.memoryUsage() }
        );
    } );
}, INTERVAL );

Note that the above script is written in a newer version of JavaScript, you might need to transpile it to make it work on your system.

And put the following code to bastion:

// file: trace-event-loop.js

'use strict';

// TODO: this library has not been put to the NMP yet.
import chart from './chart';
import clear from 'clear';

exports.local = ( traces ) => {
    let data = [];
    let delays = [];
    let POLL_INTERVAL = 1000;

    traces.on( 'eventloop:delay', ( result ) => {
        delays.push( result.delta );

        if ( delays.length >= 10 ) {
            delays.shift();
        }

        data.push( Math.max.apply( Math, delays ) );
    } );

    setInterval( () => {
        clear();

        console.log( ' EVENT LOOP DELAY ' );
        console.log( '+----------------+' );
        console.log( chart( data ) );
    }, POLL_INTERVAL );

    console.log( 'Started listening…' );
};

Note that the above script is writen in a newer version of JavaScript, you might need to transpile it to make it work on your system.

Let’s summarize what we have done:

• app: a Node.JS virtual container that publishes its event loop delay.
• bastion: An aggregation virtual container that can display those event loop delay measurements.

Now, on the bastion container (10.0.0.10), run the following:

# install `kiraz`,
# if you haven’t already done soe.
npm install kiraz -g

kiraz trace-event-loop.js

And on the app container (10.0.0.11), run the following:

node server.js

Now you should be able to see an “event loop delay” on the terminal of the “bastion” virtual container.

Hey, I'm Stuck!

For any issues that you stumble upon, feel free to open a ticket, or send and email.

Versioning and Backwards Compatibility

sif follows semantic versioning rules, and it is versioned in the "major.minor.patch" format.

• Any breaking backwards-incompatible change will increment the major version number.
• Any backwards-compatible enhancement will increment the minor version number.
• And any bug fixes that don't add extra features will increment the patch version number.

Wanna Help?

Contributors are more than welcome.

You can help make sif even better by:

• Suggesting new features by opening issues.
• Cleaning up open issues.
• Finding bugs in the code and creating issues for that.
• Forking the code, making it better, and creating pull requests.

Note

If you are planning to contribute to the source code, we won't bore you with a giant list of coding conventions :). It's your contribution that that matters.

Instead of a formal style guide, take care to maintain the existing coding style. Other than that, there's no formal contribution requirements.

Contact Information

• Project Owner: Volkan Özçelik
• Project Website: https://github.com/v0lkan/kiraz

Credits

kiraz is proudly built upon jstrace.

Thanks a lot to TJ Holowaychuk, Julian Gruber and the contributors.

License

MIT-Licensed. — See the license file for details.

Code of Conduct

We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

See the code of conduct for details.