Feature/composites

README.md

@@ -212,7 +212,11 @@ Get the 20 most recent 15 minute data point rollups for `temperature`:
 
     data = Librato::Metrics.get_measurements :temperature, :count => 20, :resolution => 900
 
-There are many more options supported for querying, take a look at the [REST API docs](http://dev.librato.com/v1/get/metrics/:name) or the [`get_metric`](http://rubydoc.info/github/librato/librato-metrics/master/Librato/Metrics/Client#get_metric-instance_method)/[`get_measurements`](http://rubydoc.info/github/librato/librato-metrics/master/Librato/Metrics/Client#get_measurements-instance_method) documentation for more details.
+Get the 5 minute moving average for `temperature` for the last hour, assuming temperature is submitted once per minute:
+
+    data = Librato::Metrics.get_composite 'moving_average(mean(series("temperature", "*"), {size: "5"}))', :start_time => Time.now.to_i - 60*60, :resolution => 300
+
+There are many more options supported for querying, take a look at the [REST API docs](http://dev.librato.com/v1/get/metrics/:name) or the individual method documentation for more details.
 
 ## Setting Metric Properties
 

lib/librato/metrics.rb

@@ -76,7 +76,7 @@ module Metrics
                    :api_endpoint=, :authenticate, :connection,
                    :faraday_adapter, :faraday_adapter=,
                    :persistence, :persistence=, :persister,
-                   :get_metric, :get_measurements, :metrics,
+                   :get_composite, :get_metric, :get_measurements, :metrics,
                    :delete_metrics, :update_metric, :update_metrics,
                    :submit,
                    :sources, :get_source, :update_source,

lib/librato/metrics/client.rb

@@ -163,6 +163,30 @@ def fetch(metric, options={})
         options.empty? ? metric : metric["measurements"]
       end
 
+      # Retrieve measurements for a given composite metric definition.
+      # :start_time and :resolution are required options, :end_time is
+      # optional.
+      #
+      # @example Get 5m moving average of 'foo'
+      #   measurements = Librato::Metrics.get_composite
+      #     'moving_average(mean(series("foo", "*"), {size: "5"}))',
+      #     :start_time => Time.now.to_i - 60*60, :resolution => 300
+      #
+      # @param [String] definition Composite definition
+      # @param [hash] options Query options
+      def get_composite(definition, options={})
+        unless options[:start_time] && options[:resolution]
+          raise "You must provide a :start_time and :resolution"
+        end
+        query = options.dup
+        query[:compose] = definition
+        url = connection.build_url("metrics", query)
+        response = connection.get(url)
+        parsed = SmartJSON.read(response.body)
+        # TODO: pagination support
+        parsed
+      end
+
       # Retrieve a specific metric by name, optionally including data points
       #
       # @example Get attributes for a metric