librato-metrics 0.6.0.pre3 → 0.6.0

data/.travis.yml

@@ -3,5 +3,12 @@ rvm:
   - ree
   - 1.9.2
   - 1.9.3
-  - jruby
-  - rbx
+  - jruby-19mode
+  - jruby-18mode
+  - rbx-19mode
+  - rbx-18mode
+  - ruby-head
+  
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## Changelog
 
+### Version 0.6.0
+* Add Aggregator class for aggregating measurements client-side
+* Queue and Aggregator can auto-submit on a time interval
+* Queue can auto-submit on a specified volume of measurements
+* Support deleting individual metrics
+* Validate user-specified measurement times
+* Update to MultiJSON 1.3 syntax
+* Run tests for rubinius and jruby in both 1.8 and 1.9 modes
+* Include request body in output for failed requests
+* Documentation improvements
+
 ### Version 0.5.0
 * Support using multiple accounts simultaneously via Client
 * Switch network library to faraday for broader platform support and flexibility

data/README.md

@@ -48,8 +48,20 @@ Queue up a simple gauge metric named `temperature`:
 
     queue = Librato::Metrics::Queue.new
     queue.add :temperature => 32.2
+    
+While symbols are used by convention for metric names, strings will work just as well:
+
+	queue.add 'myapp.request_time' => 86.7
+
+If you are tracking measurements over several seconds/minutes, the queue will handle storing measurement time for you (otherwise all metrics will be recorded as measured when they are submitted). 
 
-If you are tracking measurements over several seconds/minutes, the queue will handle storing measurement time for you (otherwise all metrics will be recorded as measured when they are submitted).
+If you want to specify a time other than queuing time for the measurement:
+
+	# use a epoch integer
+	queue.add :humidity => {:measure_time => 1336508422, :value => 48.2}
+	
+	# use a Time object to correct for a 5 second delay
+	queue.add :humidity => {:measure_time => Time.now-5, :value => 37.6}
 
 You can queue multiple metrics at once. Here's a gauge (`load`) and a counter (`visits`):
 
@@ -61,7 +73,7 @@ Queue up a metric with a specified source:
 
 A complete [list of metric attributes](http://dev.librato.com/v1/metrics) is available in the [API documentation](http://dev.librato.com/v1).
 
-Save all queued metrics:
+Send currently queued measurements to Metrics:
 
     queue.submit
 
@@ -90,7 +102,7 @@ You can aggregate multiple metrics at once:
 
     aggregator.add :app_latency => 35.2, :db_latency => 120.7
 
-Send the current aggregated metrics to Metrics:
+Send the currently aggregated metrics to Metrics:
 
     aggregator.submit
 
@@ -109,6 +121,25 @@ If you need extra attributes for a `Queue` timing measurement, simply add them o
     queue.time :my_measurement, :source => 'app1' do
       # do work...
     end
+    
+## Auto-Submitting Metrics
+
+Both `Queue` and `Aggregator` support automatically submitting measurements on a given time interval:
+
+	# submit once per minute
+	timed_queue = Librato::Metrics::Queue.new(:autosubmit_interval => 60)
+	
+	# submit every 5 minutes
+	timed_aggregator = Librato::Metrics::Aggregator.new(:autosubmit_interval => 300)
+	
+`Queue` also supports auto-submission based on measurement volume:
+
+	# submit when the 400th measurement is queued
+	volume_queue = Librato::Metrics::Queue.new(:autosubmit_count => 400)
+
+These options can also be combined for more flexible behavior. 
+
+Both options are driven by the addition of measurements. Specifically for time-based autosubmission if you are adding measurements irregularly (less than once per second), submission may lag past your specified interval until the next measurement is added.
 
 ## Querying Metrics
 
@@ -140,6 +171,15 @@ Get the 20 most recent 15 minute data point rollups for `temperature`:
 
 There are many more options supported for querying, take a look at the [REST API docs](http://dev.librato.com/v1/get/gauges/:name) or the [fetch documentation](http://rubydoc.info/github/librato/librato-metrics/master/Librato/Metrics.fetch)  for more details.
 
+## Deleting Metrics
+
+If you ever need to remove a metric and all of its measurements, doing so is easy:
+
+	# Delete the metrics 'temperature' and 'humidity'
+	Librato::Metrics.delete :temperature, :humidity
+	
+Note that deleted metrics and their measurements are unrecoverable, so use with care.
+
 ## Using Multiple Accounts Simultaneously
 
 If you need to use metrics with multiple sets of authentication credentials simultaneously, you can do it with `Client`:

data/lib/librato/metrics.rb

@@ -63,12 +63,14 @@ module Librato
     extend SingleForwardable
 
     TYPES = [:counter, :gauge]
+    MIN_MEASURE_TIME = (Time.now-(3600*24*365)).to_i
 
     # Expose class methods of Simple via Metrics itself.
     #
     def_delegators :client, :agent_identifier, :api_endpoint,
-                   :api_endpoint=, :authenticate, :connection, :fetch,
-                   :list, :persistence, :persistence=, :persister, :submit
+                   :api_endpoint=, :authenticate, :connection, :delete, 
+                   :fetch, :list, :persistence, :persistence=, :persister, 
+                   :submit
 
     # The Librato::Metrics::Client being used by module-level
     # access.

data/lib/librato/metrics/aggregator.rb

@@ -11,13 +11,13 @@ module Librato
 
       def initialize(options={})
         @aggregated = {}
-        @client = options[:client] || Librato::Metrics.client
-        @source = options[:source]
+        setup_common_options(options)
       end
 
       # Add a metric entry to the metric set:
       #
       # @param Hash metrics metrics to add
+      # @return Aggregator returns self
       def add(args)
         args.each do |k, v|
           value = v.respond_to?(:each) ? v[:value] : v
@@ -25,6 +25,8 @@ module Librato
           @aggregated[k] ||= Aggregate.new
           @aggregated[k] << value
         end
+        autosubmit_check
+        self
       end
       
       # Returns true if aggregate contains no measurements

data/lib/librato/metrics/client.rb

@@ -59,6 +59,26 @@ module Librato
         raise CredentialsMissing unless (self.email and self.api_key)
         @connection ||= Connection.new(:client => self, :api_endpoint => api_endpoint)
       end
+      
+      # Completely delete metrics with the given names. Be
+      # careful with this, this is instant and permanent.
+      #
+      # @example Delete metric 'temperature'
+      #   Librato::Metrics.delete :temperature
+      # 
+      # @example Delete metrics 'foo' and 'bar'
+      #   Librato::Metrics.delete :foo, :bar
+      def delete(*metric_names)
+        raise(NoMetricsProvided, 'Metric name missing.') if metric_names.empty?
+        params = {:names => metric_names}
+        connection.delete do |request|
+          request.url connection.build_url("metrics")
+          request.body = MultiJson.dump(params)
+        end
+        # expects 204, middleware will raise exception
+        # otherwise.
+        true
+      end
 
       # Query metric data
       #

data/lib/librato/metrics/connection.rb

@@ -27,7 +27,7 @@ module Librato
       end
       
       def transport
-        raise NoClientProvided unless @client
+        raise(NoClientProvided, "No client provided.") unless @client
         @transport ||= Faraday::Connection.new(:url => api_endpoint + "/v1/") do |f|
           #f.use FaradayMiddleware::EncodeJson
           f.use Librato::Metrics::Middleware::RequestBody

data/lib/librato/metrics/errors.rb

@@ -5,9 +5,10 @@ module Librato
     class MetricsError < StandardError; end
 
     class CredentialsMissing < MetricsError; end
-    class AgentInfoMissing < MetricsError; end
     class NoMetricsQueued < MetricsError; end
+    class NoMetricsProvided < MetricsError; end
     class NoClientProvided < MetricsError; end
+    class InvalidMeasureTime < MetricsError; end
     
     class NetworkError < StandardError; end
     

data/lib/librato/metrics/processor.rb

@@ -4,7 +4,7 @@ module Librato
     module Processor
       MEASUREMENTS_PER_REQUEST = 500
       
-      attr_reader :per_request
+      attr_reader :per_request, :last_submit_time
       
       # The current Client instance this queue is using to authenticate
       # and connect to Librato Metrics. This will default to the primary
@@ -26,9 +26,10 @@ module Librato
       #
       # @return Boolean
       def submit
-        raise NoMetricsQueued if self.queued.empty?
+        raise(NoMetricsQueued, "No metrics queued.") if self.queued.empty?
         options = {:per_request => @per_request}
         if persister.persist(self.client, self.queued, options)
+          @last_submit_time = Time.now
           flush and return true
         end
         false
@@ -72,6 +73,21 @@ module Librato
         Time.now.to_i
       end
       
+      def setup_common_options(options)
+        @autosubmit_interval = options[:autosubmit_interval]
+        @client = options[:client] || Librato::Metrics.client
+        @per_request = options[:per_request] || MEASUREMENTS_PER_REQUEST
+        @source = options[:source]
+        @create_time = Time.now
+      end
+      
+      def autosubmit_check
+        if @autosubmit_interval
+          last = @last_submit_time || @create_time
+          self.submit if (Time.now - last).to_i >= @autosubmit_interval
+        end
+      end
+      
     end
     
   end

data/lib/librato/metrics/queue.rb

@@ -1,6 +1,5 @@
 require 'metrics/processor'
 
-
 module Librato
   module Metrics
     class Queue
@@ -10,15 +9,15 @@ module Librato
 
       def initialize(options={})
         @queued = {}
-        @client = options[:client] || Librato::Metrics.client
-        @per_request = options[:per_request] || MEASUREMENTS_PER_REQUEST
+        @autosubmit_count = options[:autosubmit_count]
         @skip_measurement_times = options[:skip_measurement_times]
+        setup_common_options(options)
       end
 
       # Add a metric entry to the metric set:
       #
       # @param Hash metrics metrics to add
-      # @return Hash queued_metrics the currently queued metrics
+      # @return Queue returns self
       def add(args)
         args.each do |key, value|
           if value.respond_to?(:each)
@@ -30,13 +29,16 @@ module Librato
             type = :gauge
           end
           type = ("#{type}s").to_sym
-          unless skip_measurement_times
-            metric[:measure_time] ||= epoch_time
+          if metric[:measure_time]
+            check_measure_time(metric)
+          elsif !skip_measurement_times
+            metric[:measure_time] = epoch_time
           end
           @queued[type] ||= []
           @queued[type] << metric
         end
-        queued
+        submit_check
+        self
       end
 
       # Currently queued counters
@@ -82,6 +84,21 @@ module Librato
         self.queued.inject(0) { |result, data| result + data.last.size }
       end
       alias :length :size
+      
+    private
+    
+      def check_measure_time(data)
+        if data[:measure_time].to_i < Metrics::MIN_MEASURE_TIME
+          raise InvalidMeasureTime, "Measure time for submitted metric (#{data}) is invalid."
+        end
+      end
+    
+      def submit_check
+        autosubmit_check # in Processor
+        if @autosubmit_count && self.length >= @autosubmit_count
+          self.submit
+        end
+      end
 
     end
   end

data/lib/librato/metrics/version.rb

@@ -1,5 +1,5 @@
 module Librato
   module Metrics
-    VERSION = "0.6.0.pre3"
+    VERSION = "0.6.0"
   end
 end

data/librato-metrics.gemspec

@@ -33,9 +33,11 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rspec', '~>2.6.0'
   s.add_development_dependency 'pry'
   s.add_development_dependency 'yard'
-  s.add_development_dependency 'rdiscount' # for yard
   s.add_development_dependency 'sinatra'
   s.add_development_dependency 'popen4'
+  
+  # omitting for now because jruby-19mode can't handle
+  #s.add_development_dependency 'rdiscount' # for yard
 
   s.files = `git ls-files`.split("\n")
   s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")

data/spec/integration/metrics/queue_spec.rb

@@ -37,6 +37,7 @@ module Librato
           gauge['unassigned'][0]['value'].should == 5
         end
       end
+    
     end
     
   end

data/spec/integration/metrics_spec.rb

@@ -4,6 +4,45 @@ module Librato
   describe Metrics do
     before(:all) { prep_integration_tests }
 
+    describe "#delete" do
+      before(:each) { delete_all_metrics }
+      
+      context "with a single argument" do
+        it "should delete named metric" do
+          Metrics.submit :foo => 123
+          Metrics.list(:name => :foo).should_not be_empty
+          Metrics.delete :foo
+          Metrics.list(:name => :foo).should be_empty
+        end
+      end
+      
+      context "with multiple arguments" do
+        it "should delete named metrics" do
+          Metrics.submit :foo => 123, :bar => 345, :baz => 567
+          Metrics.delete :foo, :bar
+          Metrics.list(:name => :foo).should be_empty
+          Metrics.list(:name => :bar).should be_empty
+          Metrics.list(:name => :baz).should_not be_empty
+        end
+      end
+      
+      context "with missing metric" do
+        it "should run cleanly" do
+          # the API currently returns success even if
+          # the metric has already been deleted or is absent.
+          Metrics.delete :missing
+        end
+      end
+      
+      context "with no arguments" do
+        it "should not make request" do
+          lambda {
+            Metrics.delete
+          }.should raise_error(Metrics::NoMetricsProvided)
+        end
+      end
+    end
+
     describe "#fetch" do
       before(:all) do
         delete_all_metrics

data/spec/unit/metrics/aggregator_spec.rb

@@ -41,6 +41,10 @@ module Librato
       end
 
       describe "#add" do
+        it "should allow chaining" do
+          subject.add(:foo => 1234).should == subject
+        end
+        
         context "with single hash argument" do
           it "should record a single aggregate" do
             subject.add :foo => 3000
@@ -161,11 +165,33 @@ module Librato
             queued = subject.queued[:gauges][0]
             queued[:name].should == 'sleeping'
             queued[:count].should be 5
-            queued[:sum].should be > 500
+            queued[:sum].should be >= 500.0
             queued[:sum].should be_within(150).of(500)
           end
         end
       end
+      
+      context "with an autosubmit interval" do
+        let(:client) do
+          client = Client.new
+          client.persistence = :test
+          client
+        end
+        
+        it "should not submit immediately" do
+          timed_agg = Aggregator.new(:client => client, :autosubmit_interval => 1)
+          timed_agg.add :foo => 1
+          timed_agg.persister.persisted.should be_nil # nothing sent
+        end
+        
+        it "should submit after interval" do
+          timed_agg = Aggregator.new(:client => client, :autosubmit_interval => 1)
+          timed_agg.add :foo => 1
+          sleep 1
+          timed_agg.add :foo => 2
+          timed_agg.persister.persisted.should_not be_nil # sent
+        end
+      end
 
     end
 

data/spec/unit/metrics/queue/autosubmission_spec.rb

@@ -0,0 +1,48 @@
+require "spec_helper"
+
+module Librato
+  module Metrics
+
+    describe Queue do
+      
+      let(:client) {
+        client = Client.new
+        client.persistence = :test
+        client
+      }
+
+      context "with an autosubmit count" do
+        it "should submit when the max is reached" do
+          vol_queue = Queue.new(:client => client, :autosubmit_count => 2)
+          vol_queue.add :foo => 1
+          vol_queue.add :bar => 2
+          vol_queue.persister.persisted.should_not be_nil # sent
+        end
+        
+        it "should not submit if the max has not been reached" do
+          vol_queue = Queue.new(:client => client, :autosubmit_count => 5)
+          vol_queue.add :foo => 1
+          vol_queue.add :bar => 2
+          vol_queue.persister.persisted.should be_nil # nothing sent
+        end
+      end
+      
+      context "with an autosubmit interval" do
+        it "should not submit immediately" do
+          vol_queue = Queue.new(:client => client, :autosubmit_interval => 1)
+          vol_queue.add :foo => 1
+          vol_queue.persister.persisted.should be_nil # nothing sent
+        end
+        
+        it "should submit after interval" do
+          vol_queue = Queue.new(:client => client, :autosubmit_interval => 1)
+          vol_queue.add :foo => 1
+          sleep 1
+          vol_queue.add :foo => 2
+          vol_queue.persister.persisted.should_not be_nil # sent
+        end
+      end
+
+    end
+  end
+end

data/spec/unit/metrics/queue_spec.rb

@@ -28,6 +28,10 @@ module Librato
       end
 
       describe "#add" do
+        it "should allow chaining" do
+          subject.add(:foo => 123).should == subject
+        end
+        
         context "with single hash argument" do
           it "should record a key-value gauge" do
             expected = {:gauges => [{:name => 'foo', :value => 3000, :measure_time => @time}]}
@@ -78,6 +82,32 @@ module Librato
             subject.queued.should equal_unordered(expected)
           end
         end
+        
+        context "with a measure_time" do
+          it "should accept time objects" do
+            time = Time.now-5
+            subject.add :foo => {:measure_time => time, :value => 123}
+            subject.queued[:gauges][0][:measure_time].should == time
+          end
+          
+          it "should accept integers" do
+            time = 1336574713
+            subject.add :foo => {:measure_time => time, :value => 123}
+            subject.queued[:gauges][0][:measure_time].should == time
+          end
+          
+          it "should accept strings" do
+            time = '1336574713'
+            subject.add :foo => {:measure_time => time, :value => 123}
+            subject.queued[:gauges][0][:measure_time].should == time
+          end
+          
+          it "should raise exception in invalid time" do
+            lambda {
+              subject.add :foo => {:measure_time => '12', :value => 123}
+            }.should raise_error(InvalidMeasureTime)
+          end
+        end
       end
 
       describe "#counters" do
@@ -115,6 +145,19 @@ module Librato
         end
       end
       
+      describe "#last_submit_time" do
+        it "should default to nil" do
+          subject.last_submit_time.should be_nil
+        end
+        
+        it "should store last submission time" do
+          prior = Time.now
+          subject.add :foo => 123
+          subject.submit
+          subject.last_submit_time.should >= prior
+        end
+      end
+      
       describe "#per_request" do
         it "should default to 500" do
           subject.per_request.should == 500
@@ -186,7 +229,7 @@ module Librato
         end
       end
 
-    end # MetricSet
+    end # Queue
 
   end
 end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: librato-metrics
 version: !ruby/object:Gem::Version
-  version: 0.6.0.pre3
-  prerelease: 6
+  version: 0.6.0
+  prerelease: 
 platform: ruby
 authors:
 - Matt Sanders
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-26 00:00:00.000000000Z
+date: 2012-05-09 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
-  requirement: &70105435038240 !ruby/object:Gem::Requirement
+  requirement: &70349186771660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 0.7.6
   type: :runtime
   prerelease: false
-  version_requirements: *70105435038240
+  version_requirements: *70349186771660
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &70105435037740 !ruby/object:Gem::Requirement
+  requirement: &70349186771180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.3.1
   type: :runtime
   prerelease: false
-  version_requirements: *70105435037740
+  version_requirements: *70349186771180
 - !ruby/object:Gem::Dependency
   name: aggregate
-  requirement: &70105435037280 !ruby/object:Gem::Requirement
+  requirement: &70349186770720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 0.2.2
   type: :runtime
   prerelease: false
-  version_requirements: *70105435037280
+  version_requirements: *70349186770720
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70105435036900 !ruby/object:Gem::Requirement
+  requirement: &70349186802320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70105435036900
+  version_requirements: *70349186802320
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70105435068860 !ruby/object:Gem::Requirement
+  requirement: &70349186801780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *70105435068860
+  version_requirements: *70349186801780
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70105435068440 !ruby/object:Gem::Requirement
+  requirement: &70349186801360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70105435068440
+  version_requirements: *70349186801360
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70105435067980 !ruby/object:Gem::Requirement
+  requirement: &70349186800900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,21 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70105435067980
-- !ruby/object:Gem::Dependency
-  name: rdiscount
-  requirement: &70105435067560 !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: *70105435067560
+  version_requirements: *70349186800900
 - !ruby/object:Gem::Dependency
   name: sinatra
-  requirement: &70105435067140 !ruby/object:Gem::Requirement
+  requirement: &70349186800480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70105435067140
+  version_requirements: *70349186800480
 - !ruby/object:Gem::Dependency
   name: popen4
-  requirement: &70105435066720 !ruby/object:Gem::Requirement
+  requirement: &70349186800060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,7 +109,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70105435066720
+  version_requirements: *70349186800060
 description: An easy to use ruby wrapper for Librato's Metrics API
 email: matt@librato.com
 executables: []
@@ -162,6 +151,7 @@ files:
 - spec/unit/metrics/aggregator_spec.rb
 - spec/unit/metrics/client_spec.rb
 - spec/unit/metrics/connection_spec.rb
+- spec/unit/metrics/queue/autosubmission_spec.rb
 - spec/unit/metrics/queue_spec.rb
 - spec/unit/metrics_spec.rb
 homepage: https://github.com/librato/librato-metrics
@@ -180,9 +170,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.16
@@ -199,6 +189,7 @@ test_files:
 - spec/unit/metrics/aggregator_spec.rb
 - spec/unit/metrics/client_spec.rb
 - spec/unit/metrics/connection_spec.rb
+- spec/unit/metrics/queue/autosubmission_spec.rb
 - spec/unit/metrics/queue_spec.rb
 - spec/unit/metrics_spec.rb
 has_rdoc: