Node installation and configuration

The Errplane Node library is open source and can be found on Github. Pull requests welcome!

First, install the library with npm:

npm install errplane

Load and configure the Errplane object:

var errplane = require('errplane').configure({
  apiKey: "1234-5678-abcdefgh-wxyz",
  applicationId: "a1b2c3d4"
});

By default, the library will attempt to use NODE_ENV for the environment, but it will default to development. You can override this value by supplying the environment key in the configuration hash:

var errplane = require('errplane').configure({
  apiKey: "1234-5678-abcdefgh-wxyz",
  applicationId: "a1b2c3d4",
  environment: "staging"
});

Usage with Express

This library has built-in support for Express. Currently, it supplies middleware that can report exceptions and basic performance data.

Reporting Exceptions

Since middleware load order is rather important in Express, it's suggested that you put the exception handler last, right before you call app.listen(...).

Insert the Errplane exception middleware as follows:

app.use(errplane.expressExceptionHandler());

Reporting Request Response Time

Again, since middleware load order is important, you'll want to put the response time handler first, before any other middleware.

app.use(errplane.expressResponseTimeReporter());

Reporting Uncaught Exceptions

First, you can tell Errplane to start reporting uncaught exceptions:

errplane.reportUncaughtExceptions();

Note that the library will reraise these exceptions after they're reported, so your application will still crash afterwards.

Metrics and Instrumentation

Sending Metrics

Errplane allows you to send custom metrics, so that you can instrument any portion of your application.

Our API is designed to let you to send data in two main ways. Sending a raw data point will always write a single point into a time series. Sending data to our aggregation end point will allow you to write either rollups or counts to a time series on 1-minute intervals.

errplane.report("queue_depth", {value: queue.length});

You can include a context that will get turned into JSON (if it's not already a string) and stored in the API along with the data point:

errplane.report("new_user", {context: user.email})

And dimensions will allow you to send a hash defines attributes that you can use for filtering later:

errplane.report("response_time", value: time_in_ms, dimensions: {
  server: "app1", method: "executeQuery"})

Sending Rollups

Data sent to our rollup aggregator will be collected and averaged every minute. The result will be subsequently written to the time series indicated. The interface is very similar to the raw data interface:

errplane.aggregate("a_frequent_action", {value: elapsed_time})

Sending Counts

Data sent to our count aggregator will be stored and summed every minute. The result will be subsequently written to the time series indicated. The interface is very similar to the raw data interface:

errplane.sum("home_page_visits", {value: 1})

Heartbeats

errplane.heartbeat("background_worker", 5000);

Timing Synchronous Functions

syncThing = function() {
  // perform complex calculation here
}

timedSyncThing = errplane.timeSync("sync_thing_runtime", syncThing)
value = timedSyncThing();

Timing Asynchronous Functions

asyncThing = function(value, callback) {
  setTimeout(function () {
    callback(value);
  }, 100)
}

timedAsyncThing = errplane.timeAsync("async_thing_runtime", asyncThing);

timedAsyncThing(99, function(value) {
  console.log(value)
})