concurix

The Concurix Node.js tracer.

Instruments your code in two ways:

1. Instruments all of your (and 3rd-party) javascript functions in order to build flame graphs of your synchronous code.
2. Wraps key asynchronous functions to trace transactions crossing the event-loop boundary.

The data is collected as your application runs, aggregated and sent periodically to the Concurix service where you can analyze and track your application over time at http://concurix.com

The net result is the ability to track execution across asynchronous boundaries in your application, I.e. see a http request against your Node.js server from start-to-finish, with flame graphs of the js code and transaction timinigs for things like database queries.

It provides a holistic view of what your Node.js application is doing, with only a single require statement.

API

var concurix = require("concurix")(options)

Before any other require statements in your main entry code, require("concurix") to install the instrumentation, and provide your account key. You can get an account key at Concurix.com.

E.g.

var concurix = require("concurix")({
  accountKey: "YOUR ACCOUNT KEY",
  email: "your@email.address"
})

Note that this will not currently be able to instrument ANY functions that are defined in the file where concurix is required. For applications that define most logic in the entry js file, the best way to work around this is to use a wrapper when you want to run with the tracer that requires your file after starting instrumentation, e.g.:

var concurix = require("concurix")({
  accountKey: "YOUR ACCOUNT KEY",
  email: "your@email.address"
})
require("your_main_entrypoint.js")

Options:

var DEFAULT_CONFIG = {
  "accountKey": "YOUR ACCOUNT KEY", // REQUIRED
  "email": "your@email.address", // So we can follow up with you
  "archiveInterval": 60000, // An *approximate* trace interval. Valid values: 5000-60000
 
  // Tracer configuration
  "instrument": true, // Instrument synchronous JS code for generating flame graphs.
  "trace": true, // Toggle trace collection on or off (requires instrument: true)
  "transactions": true, // Toggle transaction collection on or off
  "follow_links": true, // While aggregating waterfalls follow accross the event loop. Disable for faster aggregation but only flamegraphs.
  "enable_cca": false, // Enable for a lossy on-the-fly flamegraph compression. Helps for performance.
 
  // Wrapping of core modules
  "wrap_core": true, // Quickly disable wrapping all core modules
  "wrap_timers": true, // Wrap setTimeout, setInterval, setImmediate
  "wrap_process": true, // Wrap process.nextTick
  "wrap_dns": true, // Wrap the core dns module
  "wrap_fs": true, // Wrap the core fs module
  "wrap_http": true, // Wrap the core http and https modules
  "wrap_zlib": true, // Wrap the core zlib module
 
  // Third party special-cased modules.
  "wrap_redis": true, // Wrap the redis module if present
 
  // Third party native modules
  "wrap_native": true, // Not yet implemented
 
  "blacklist": [] // See below for blacklist
}

Running with the default options is suggested.

Blacklisting:

The blacklist can be used to prevent instrumentation of specific files. It expects a list of file globs, and if the filename of the module being required matches, it will skip it. E.g.

  "blacklist": [
    "*/foo.js",  // block any file named `foo.js`
    "*node_modules/foo/*", // block anything under module `foo`
  ]

Tagging:

Waterfalls can be "tagged" manually for grouping or search in the UI by using the tag() method. E.g.

var concurix = require("concurix")(options)
 
function setWidget(bar) {
  concurix.tracer.tag("setting widget " + bar)
  // ...
}

Some tagging is done automatically for pre-wrapped modules.

Custom Metrics:

The concurix tracer includes the http://npm.im/statware module and can send custom metrics to be stored with your trace files.

var concurix = require("concurix")(options)
 
var metrics = concurix.metrics()
metrics.increment("widgets")

See the http://npm.im/statware documentation for more information.

For more information, see Concurix.com

LICENSE

Concurix Terms of Service