Looks ready for release

Readme.md

@@ -127,11 +127,15 @@ http.createServer(function(req, res) {
 
 ### Histogram
 
-Things that are measured as distributions of numbers. Example:
+Things that are measured as distributions of scalars. Example:
 
 ```js
 var histogram = new metrics.Histogram();
-histogram.update(5);
+http.createServer(function(req, res) {
+  if (req.headers['content-length']) {
+    histogram.update(parseInt(req.headers['content-length'], 10));
+  }
+});
 ```
 
 **Options:**
@@ -143,6 +147,45 @@ histogram.update(5);
 * `update(value, timestamp)` Pushes `value` into the sample. `timestamp`
   defaults to `Date.now()`.
 
-## Todo
+### Timers
+
+Timers are a combination of Meters and Histograms. They measure the rate as
+well as distribution of scalar events. Since they are frequently used for
+tracking how long certain things take, they expose an API for that:
+
+```js
+var timer = new metrics.Timer();
+http.createServer(function(req, res) {
+  var stopwatch = timer.start();
+  req.on('end', function() {
+    stopwatch.end();
+  });
+});
+```
+
+But you can also use them as generic histograms that also track the rate of
+events:
+
+```js
+var timer = new metrics.Timer();
+http.createServer(function(req, res) {
+  if (req.headers['content-length']) {
+    timer.update(parseInt(req.headers['content-length'], 10));
+  }
+});
+```
+
+**Options:**
+
+* `meter` The internal meter to use. Defaults to a new `Meter`.
+* `histogram` The internal histogram to use. Defaults to a new `Histogram`.
+
+**Methods:**
+
+* `start()` Returns a `Stopwatch`.
+* `update(value)` Updates the internal histogram with `value` and marks one
+  event on the internal meter.
+
+## License
 
-* Finish Readme : )
+This module is licensed under the MIT license.

example/http_requests_per_second.js

@@ -4,10 +4,11 @@ var http       = require('http');
 
 var rps = collection.meter('requestsPerSecond');
 http.createServer(function(req, res) {
-  meter.mark();
+  console.error(req.headers['content-length']);
+  rps.mark();
   res.end('Thanks');
 }).listen(3000);
 
 setInterval(function() {
   console.log(collection.toJSON());
-}, 1000
+}, 1000);

lib/metrics/Timer.js

@@ -12,7 +12,7 @@ Timer.prototype.start = function() {
   var self  = this;
   var watch = new Stopwatch();
 
-  watch.once('stop', function(elapsed) {
+  watch.once('end', function(elapsed) {
     self.update(elapsed);
   });
 

lib/util/Stopwatch.js

@@ -6,18 +6,16 @@ util.inherits(Stopwatch, EventEmitter);
 function Stopwatch() {
   EventEmitter.call(this);
 
-  this._start   = Date.now();
-  this._stopped = false;
+  this._start = Date.now();
+  this._ended = false;
 }
 
-Stopwatch.prototype.stop = function() {
-  // Ideally this would throw, but having your metrics library throw in
-  // production would be really annoying, right?
-  if (this._stopped) return;
+Stopwatch.prototype.end = function() {
+  if (this._ended) return;
 
-  this._stopped = true;
+  this._ended = true;
   var elapsed   = Date.now() - this._start;
 
-  this.emit('stop', elapsed);
+  this.emit('end', elapsed);
   return elapsed;
 };

test/unit/metrics/test-Timer.js

@@ -52,7 +52,7 @@ test('Timer', {
 
     var watch = timer.start();
     clock.tick(50);
-    watch.stop();
+    watch.end();
 
     assert.ok(meter.mark.calledOnce);
     assert.equal(histogram.update.args[0][0], 50);

test/unit/util/test-Stopwatch.js

@@ -16,44 +16,44 @@ test('Stopwatch', {
     clock.restore();
   },
 
-  'returns time on stop': function() {
+  'returns time on end': function() {
     clock.tick(10);
 
     var watch = new Stopwatch();
     clock.tick(100);
 
-    var elapsed = watch.stop();
+    var elapsed = watch.end();
     assert.equal(elapsed, 100);
   },
 
-  'emits time on stop': function() {
+  'emits time on end': function() {
     var watch = new Stopwatch();
     clock.tick(20);
 
     var time;
-    watch.on('stop', function(_time) {
+    watch.on('end', function(_time) {
       time = _time;
     });
 
-    watch.stop();
+    watch.end();
 
     assert.equal(time, 20);
   },
 
-  'becomes useless after being stopped once': function() {
+  'becomes useless after being ended once': function() {
     var watch = new Stopwatch();
     clock.tick(20);
 
     var time;
-    watch.on('stop', function(_time) {
+    watch.on('end', function(_time) {
       time = _time;
     });
 
-    assert.equal(watch.stop(), 20);
+    assert.equal(watch.end(), 20);
     assert.equal(time, 20);
 
     time = null;
-    assert.equal(watch.stop(), undefined);
+    assert.equal(watch.end(), undefined);
     assert.equal(time, null);
   },
 });