kiraz v0.2.4
__.--~~.,-.__
`~-._.-(`-.__`-.
\
\--.
/# \
,--. \ /
| |,-. '--' ,--.--. ,--,--. ,-----.
| / | | | .--' ' ,-. | `-. /
| \ \ | | | | \ '-' | / `-.
`--'`-- 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.