support histograms

in accordance with existing codebase, implement this in graphite
backend

README.md

@@ -51,6 +51,13 @@ generate the following list of stats for each threshold:
 Where `$KEY` is the key you stats key you specify when sending to statsd, and
 `$PCT` is the percentile threshold.
 
+If `config.histogram` is set to a non-zero array, statsd will also
+maintain frequencies for each bin as specified by the (non-inclusive)
+upper limits in the array. (`'inf'` can be used to denote infinity,
+which is highly recommended, as high outliers will not be accounted for if
+your last upper limit is too low).
+a lower limit of 0 is assumed.
+
 Sampling
 --------
 

backends/graphite.js

@@ -15,6 +15,7 @@
 var net = require('net'),
    util = require('util');
 
+var config;
 var debug;
 var flushInterval;
 var graphiteHost;
@@ -125,6 +126,18 @@ var flush_stats = function graphite_flush(ts, metrics) {
       message += 'stats.timers.' + key + '.count ' + count + ' ' + ts + "\n";
       message += 'stats.timers.' + key + '.sum ' + sum  + ' ' + ts + "\n";
       message += 'stats.timers.' + key + '.mean ' + mean + ' ' + ts + "\n";
+
+      // note: values bigger than the upper limit of the last bin are ignored, by design
+      num_bins = (config.histogram || []).length
+      var i = 0;
+      for (var bin_i = 0; bin_i < num_bins; bin_i++) {
+        var freq = 0;
+        for (; i < count && (config.histogram[bin_i] == 'inf' || values[i] < config.histogram[bin_i]); i++) {
+          freq += 1;
+        }
+        message += 'stats.timers.' + key + '.bin_' + config.histogram[bin_i] + ' ' + freq  + ' ' + ts + "\n";
+      }
+
       statString += message;
 
       numStats += 1;
@@ -152,7 +165,8 @@ var backend_status = function graphite_status(writeCb) {
   }
 };
 
-exports.init = function graphite_init(startup_time, config, events) {
+exports.init = function graphite_init(startup_time, conf, events) {
+  config = conf
   debug = config.debug;
   graphiteHost = config.graphiteHost;
   graphitePort = config.graphitePort;

exampleConfig.js

@@ -27,9 +27,6 @@ Optional Variables:
   debugInterval:    interval to print debug information [ms, default: 10000]
   dumpMessages:     log all incoming messages
   flushInterval:    interval (in ms) to flush to Graphite
-  percentThreshold: for time information, calculate the Nth percentile(s)
-                    (can be a single value or list of floating-point values)
-                    [%, default: 90]
   keyFlush:         log the most frequently sent keys [object, default: undefined]
     interval:       how often to log frequent keys [ms, default: 0]
     percent:        percentage of frequent keys to log [%, default: 100]
@@ -49,6 +46,15 @@ Optional Variables:
                     packets should be "repeated" (duplicated to).
                     e.g. [ { host: '10.10.10.10', port: 8125 },
                            { host: 'observer', port: 88125 } ]
+  timer:
+    percentThreshold: calculate the Nth percentile(s)
+                    (can be a single value or list of floating-point values)
+                    [%, default: 90]
+    histogram:      an array of ordered non-inclusive upper limits of bins for
+                    histogram (in ms).  'inf' means infinity. (default: [])
+                    if non-empty, histograms are enabled and frequencies
+                    for each bin are written.
+                    e.g. [ 25, 50, 100, 150, 200, 'inf' ]
 */
 {
   graphitePort: 2003