Oxide.js NPM | npm.io

oxide.js

Oxide is a Node.js client designed for easy communicating with Carbon, a data injest tool which is a part of the Graphite project. Oxide also works well with Statsd, a fantastic little tool from the folks at Etsy designed for more powerful metrics recording.

Installation

oxide.js is a npm package, so installation couldn't be easier. To install oxide.js as a dependency, simply execute:

$ npm install oxide.js --save

And then require oxide in your project:

var Oxide = require('oxide.js');

Theory of Operation

oxide.js is a pretty simple tool. It aggregates metrics using the #record method, and then compacts them using either one of two protocols, the pickle protocol or the plaintext protocol. On a given interval (see the usage section), the protocol will compact all of the Metrics in the client's queue, send them over the socket, and dump the queue.

When using Oxide.js in Statsd mode, it will aggregate the stats using the same queueing method as in carbon mode, however, it will not use a protocol to compact the data, instead, it will pack each metric individually, create a buffer, and send that. At this time, Statsd does not allow for protocol-based metric sending over UDP.

The queuing operations are thread-safe.

Usage

Once you have the oxide.js namespace in your project, usage is pretty simple. To construct an oxide client, simply pass an object containing your arguments to the constructor, i.e.:

var Oxide = require('oxide.js');

/**
 * The following options are supported:
 *   host: the hostname of your carbon server
 *   port: the port your carbon server runs on
 *   prefix: prefixes all paths with the given value (i.e., foo -> prefix.foo)
 *   interval: the time in msec to send statistics
 *   protocol: an instance of the protocol to send statistics with
 */
var oxideClient = new Oxide.Client.CarbonClient({
  host: '127.0.0.1',
  port: 2003,
  interval: 5000
});

To write a metric into Oxide's aggregate queue, simply fire off the #record method:

// Connect to the server oxideClient.connect();

// Start the queuing operations oxideClient.start();

/**
 * #record takes three arguments, as described below:
 *   1) path - the path to write the metric to
 *   2) value - the value to write onto the metric
 *   3) [optional] timestamp - the time to record the metric
 */
oxideClient.record('my.path', 50, new Date());

A call to #record makes a new Oxide.Metric and dumps it in the queue. After the time specified in the interval, oxide.js will collect all statistics currently in the queue, and pack them using the protocol, then send them up the wire.

The Statsd client is more interesting, since statsd supports more metric types. All protocols described in this spec are implemented by the client using a different method call. Examples follow below:

var client = new Oxide.Client.StastdClient({ /* opts */ });
client.connect();
client.start();

// Send a counter metric to increment the `path` argument by 1, or the amount specified.
client.increment(path[, amount[, sampleRate]]);

// Send a counter metric to decrement the `path` given by 1, otherwise the amount specified.
client.decrement(path[, amount[, sampleRate]]);

// Send a gauge metric to set the value of `path` to the amount specified.
client.gauge(path, amount);

// Send a timer metric to mark the time of the `path` to the amount specified.
client.timing(path, duration); // duration in msec

That's it!