Add the real stuff.

README.md

@@ -1,4 +1,70 @@
-statsd-http-api
-===============
+# statsd-http-api
 
 A statsd backend that exposes the latest aggregated metrics via a simple HTTP API.
+
+## API
+
+[Statsd][statsd] internally keeps all metrics in a javascript object of the form:
+
+    {
+      "counters": {
+        "statsd.bad_lines_seen": 0,
+        "statsd.packets_received": 3,
+        "test.hello": 3
+      },
+      "gauges": {},
+      "timers": {},
+      "timer_counters": {},
+      "sets": {},
+      "counter_rates": {
+        "statsd.bad_lines_seen": 0,
+        "statsd.packets_received": 0.2,
+        "test.hello": 0.2
+      },
+      "timer_data": {},
+      "pctThreshold": [
+        90
+      ],
+      "statsd_metrics": {
+        "processing_time": 0
+      }
+    }
+
+Using the API, you can access all parts of the metrics object via obvious URLs:
+
+ * `GET /counters/test.hello` returns `3`
+
+ * `GET /counter_rates` returns:
+
+        {
+          "statsd.bad_lines_seen": 0,
+          "statsd.packets_received": 0.2,
+          "test.hello": 0.2
+        }
+
+ * `GET /` returns the whole metrics object.
+
+## Installation
+
+Copy `statsd-http-api.js` into the `statsd/backends` folder of your local statsd installation.  Then change the statsd configuration file to include the `statsd-http-api` in the backend list:
+
+    {
+      "backends": ["backends/statsd-http-server"]
+    }
+
+## Run
+
+    node statsd.js config.js
+
+The http server listens on TCP port 8127.  Test that everything is working by visiting `http://localhost:8127`
+
+## Use it with Cubism
+
+This backend was designed to expose metrics for graph visualization using [cubism][cubism].
+
+Check out [cubismino][cubismino] to get up and running with statsd and cubism.
+
+[statsd]: http://statsd
+[cubism]: https://github.com/square/cubism
+[cubismino]: https://github.com/mrucci/cubismino
+

statsd-http-api.js

@@ -0,0 +1,52 @@
+var util = require('util');
+var http = require('http');
+var url  = require('url');
+
+function HttpServerBackend(startupTime, config, emitter) {
+    var self = this;
+    self.metrics = {}
+    self.headers = {'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*'}
+    emitter.on('flush', function(timestamp, metrics) { self.flush(timestamp, metrics); });
+};
+
+HttpServerBackend.prototype.flush = function(timestamp, metrics) {
+    this.metrics = JSON.parse(JSON.stringify(metrics))
+};
+
+HttpServerBackend.prototype.respond = function(res, statusCode, obj) {
+    res.writeHead(statusCode, this.headers)
+    res.end(JSON.stringify(obj, undefined, 2));
+}
+
+HttpServerBackend.prototype.serve = function() {
+    var self = this
+    http.createServer(function (req, res) {
+
+        if(req.url == '' || req.url == '/') {
+            return self.respond(res, 200, self.metrics)
+        }
+
+        path = url.parse(req.url.slice(1)).pathname.split('/')
+        try {
+            if(path.length == 1) {
+                metrics = self.metrics[path[0]]
+            } else if(path.length == 2) {
+                metrics = self.metrics[path[0]][path[1]]
+            } else if(path.length == 3) {
+                metrics = self.metrics[path[0]][path[1]][path[2]]
+            } else {
+                return self.respond(res, 404, '')
+            }
+            return self.respond(res, 200, metrics)
+        } catch(e) {
+            return self.respond(res, 404, '' + e)
+        }
+        return self.respond(res, 500, '')
+    }).listen(8127);
+
+    return true
+};
+
+exports.init = function(startupTime, config, events) {
+    return new HttpServerBackend(startupTime, config, events).serve();
+};