re-write metric api

lib/api/metric.js

@@ -1,59 +1,143 @@
-var metric_api = function(){};
+var client = require("../client");
 
-metric_api.prototype.add_metric = function(metric, callback){
-    /*
-     * metric_api.add_metric(metric, [callback])
-     *
-     * method used to add a single metric to datadog
-     *
-     * `metric` an object representation of the metric
-     *     metric: *required*, the name of the metric
-     *     points: *required*, an array of elements [ timestamp, value ]
-     *     host: name of the host that produced the event
-     *     tags: array of tags to associate with the event
-     *     type: "guage" or "counter"
-     *
-     * `callback` an optional function to call with the results
-     *     callback(metric, [callback])
-    */
-    var metrics = {
-        'series': [metric]
-    };
-    this.add_metrics(metrics, callback);
-};
 
-metric_api.prototype.add_metrics = function(metrics, callback){
-    /*
-     * metric_api.add_metrics(metrics, [callback])
-     *
-     * method used to add multiple metrics to datadog
-     *
-     * `metrics` an object representation of the metric:
-     *     series: an array of `metrics` to add
-     *
-     * `callback` an optional function to call with the results
-     *     callback(metric, [callback])
-    */
-    if(typeof metrics != 'object'){
-        throw new Error('`metrics` parameter must be an object');
+/*section: metric
+ *comment: |
+ *  submit a new metric
+ *params:
+ *  metric: the metric name
+ *  points: |
+ *    single datapoint or array of [timestamp, datapoint], if a single point
+ *    is given "now" is used as the timestamp
+ *  extra: |
+ *    optional, object which can contain the following keys
+ *    * host: the host source of the metric
+ *    * tags: array of "tag:value"'s to use for the metric
+ *    * metric_type: which metric type to use ("gauge" or "counter") [default: gauge]
+ *  callback: |
+ *    function(err, res)
+ *example: |
+ *  ```javascript
+ *   var dogapi = require("dogapi");
+ *   var options = {
+ *     api_key: "api_key",
+ *     app_key: "app_key"
+ *   };
+ *   dogapi.initialize(options);
+ *   dogapi.metric.send("my.metric", 1000, function(err, results){
+ *     console.dir(results);
+ *   });
+ *   var now = parseInt(new Date().getTime() / 1000);
+ *   dogapi.metric.send("my.metric", [now, 1000], function(err, results){
+ *     console.dir(results);
+ *   });
+ *  ```
+ */
+function send(metric, points, extra, callback){
+    if(arguments.length < 4 && typeof arguments[2] === "function"){
+        callback = tags;
+        extra = {};
     }
 
-    if(!metrics['series'] || typeof metrics['series'] != 'object'){
-        throw new Error('`metrics["series"]` parameter must be an array');
-    }
-
-    for(var i in metrics['series']){
-        var metric = metrics['series'][i];
-        if(!metric['metric']){
-            throw new Error('metric["metric"] is required');
+    extra = extra || {};
+    var series = [
+        {
+            metric: metric,
+            points: points,
+            host: extra.host,
+            tags: extra.tags,
+            metric_type: extra.metric_type
         }
+    ];
+
+    send_all(series, callback);
+}
 
-        if(!metric['points'] || typeof metric['points'] != 'object'){
-            throw new Error('metric["points"] must be an array');
+/*section: metric
+ *comment: |
+ *  send a list of metrics
+ *params:
+ *  metrics: |
+ *    an array of metrics where each element is an object with the following keys
+ *    * metric: the name of the metric
+ *    * points: a single datapoint or an array of [timestamp, datapoint] (same as `dogapi.metric.send`)
+ *    * tags: an array of "tag:value"'s
+ *    * host: the source hostname to use for the metrics
+ *    * metric_type: the type of metric to use ("gauge" or "counter") [default: gauge]
+ *  callback: |
+ *    function(err, res)
+ *example: |
+ *  ```javascript
+ *   var dogapi = require("dogapi");
+ *   var options = {
+ *     api_key: "api_key",
+ *     app_key: "app_key"
+ *   };
+ *   dogapi.initialize(options);
+ *   var now = parseInt(new Date().getTime() / 1000);
+ *   var metrics = [
+ *     {
+ *       metric: "my.metric",
+ *       points: [now, 1000],
+ *       tags: ["tag:value"]
+ *     },
+ *     {
+ *       metric: "another.metric",
+ *       points: 1000
+ *     }
+ *   ];
+ *   dogapi.metric.send_all(metrics, function(err, results){
+ *     console.dir(results);
+ *   });
+ *  ```
+ */
+function send_all(metrics, callback){
+    var now = parseInt(new Date().getTime() / 1000);
+    for(var i = 0; i < metrics.length; ++i){
+        if(!Array.isArray(metrics[i].points)){
+            metrics[i].points = [now, metrics[i].points];
         }
     }
+    var params = {
+        body: metrics
+    };
+    client.request("POST", "/series", params, callback);
+}
 
-    this.request('POST', '/series', {body: metrics}, callback);
-};
+/*section: metric
+ *comment: |
+ *  make a metric query
+ *params:
+ *  from: POSIX timestamp for start of query
+ *  to: POSIX timestamp for end of query
+ *  query: the string query to perform (e.g. "system.cpu.idle{*}by{host}")
+ *  callback: function(err, res)
+ *example: |
+ *  ```javascript
+ *   var dogapi = require("dogapi");
+ *   var options = {
+ *     api_key: "api_key",
+ *     app_key: "app_key"
+ *   };
+ *   dogapi.initialize(options);
+ *   var now = parseInt(new Date().getTime() / 1000);
+ *   var then = now - 3600; // one hour ago
+ *   var query = "system.cpu.idle{*}by{host}";
+ *   dogapi.metric.query(then, now, query, function(err, res){
+ *     console.dir(res);
+ *   });
+ *  ```
+ */
+function query(from, to, query, callback){
+    var params = {
+        from: from,
+        to: to,
+        query: query
+    };
+    client.request("GET", "/query", params, callback);
+}
 
-return module.exports = metric_api;
+module.exports = {
+    send: send,
+    send_all: send_all
+};