sakaiproject/Hilary — pull request #168 by simong (2012-10-05 16:42:08+00:00)
Title: Telemetry module

This PR introduces a new telemetry module.

It supports the following basic methods:
* `incr` for basic counting
* `append` for collecting multiple values (ex: to generate histograms)
* `registerURL` for measuring HTTP request/response times.

It has the following publishers
* `console`
* `circonus`

Adding new publishes shouldn't be a problem as publishers can just retrieve the raw statistics.
This could potentially be used to generate pretty graphs, get the max response time of an API request, etc..

## Usage
You can create a `Telemetry` object for your module by doing:
```javascript
var Telemetry = require('oae-telemetry').telemetry('cassandra');
```

Increasing a counter can be done with:
```javascript
Telemetry.incr('write');
```
Appending a value to something:
```javascript
Telemetry.append('foo', 34);
```

For measuring the latency of a URL request you'll need to register your endpoint with a compiled regex.
Keep in mind that the order of registered url's is important.
```javascript
TelemetryAPI.registerURL(/^\/api\/auth\/login$/, 'auth.login');
```

## Console Publisher
This is intended for development mode or quick debugging on a single app node.
It publishes all the collected data to stdout every 5 seconds in the following format:
```
[2012-10-05T15:40:54.998Z] INFO: telemetry-console/42266 on dhcp-56.caret.private: cassandra read 1233
[2012-10-05T15:40:54.999Z] INFO: telemetry-console/42266 on dhcp-56.caret.private: cassandra write 599
[2012-10-05T15:40:54.999Z] INFO: telemetry-console/42266 on dhcp-56.caret.private: requests POST 316
[2012-10-05T15:40:54.999Z] INFO: telemetry-console/42266 on dhcp-56.caret.private: requests POST.auth.login.count 16
[2012-10-05T15:40:55.000Z] INFO: telemetry-console/42266 on dhcp-56.caret.private: requests POST.group.create.count 301
[2012-10-05T15:40:55.000Z] INFO: telemetry-console/42266 on dhcp-56.caret.private: requests POST.auth.login.time 48, 39, 32, 57, 24, 25, 52, 37, 33, 29, 19, 31, 60, 64, 42, 19
[2012-10-05T15:40:55.001Z] INFO: telemetry-console/42266 on dhcp-56.caret.private: requests POST.group.create.time 62, 62, 59, 67, 60, 75, 52, 45, 74, 59, 69, 35, 40, 51, 35, 36
```

## Circonus publisher
All the counts get pushed to redis in a `telemetry` hash and all the histogram data gets pushed to circonus via httptrap. There is a small delay between pushing data and visualizing it in the circonus UI (~2 minutes).
you'll have to setup 2 checks in circonus
* a redis check (unfortunately circonus only supports getting data from dbIndex `0`, I've asked them and they created an outstanding ticket for it https://github.com/omniti-labs/reconnoiter/issues/112)
* an http trap check. They'll present you with a URL to PUT to which you need to stick in our root config.js