librato-metrics 0.6.1 → 0.7.0

data/.rspec

@@ -0,0 +1 @@
+--colour

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## Changelog
 
+### Version 0.7.0
+* Add ability to update metric properties (Christoph Bünte)
+* Add ability to merge queue and aggregator data into a queue
+* Aggregator supports custom source by measurement
+* Add option to clear queued measurements after failed submit
+* Custom user agent support
+* Documentation improvements
+
 ### Version 0.6.1
 * Loosen restrictions to older versions of faraday and multi_json
 * Fix symbol casting issue in jruby with metric delete

data/Gemfile

@@ -4,4 +4,9 @@ platforms :jruby do
   gem 'jruby-openssl'
 end
 
-gemspec
+platforms :ruby do
+  # make available for yard under C rubies
+  gem 'redcarpet'
+end
+
+gemspec

data/lib/librato/metrics.rb

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

data/lib/librato/metrics/aggregator.rb

@@ -5,8 +5,10 @@ module Librato
   module Metrics
 
     class Aggregator
-      include Processor
+      SOURCE_SEPARATOR = '%%' # must not be in valid source name criteria
       
+      include Processor
+
       attr_reader :source
 
       def initialize(options={})
@@ -16,14 +18,21 @@ module Librato
 
       # 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
+      # @param [Hash] measurements measurements to add
+      # @return [Aggregator] returns self
+      def add(measurements)
+        measurements.each do |metric, data|
+          if data.respond_to?(:each) # hash form
+            value = data[:value]
+            if data[:source]
+              metric = "#{metric}#{SOURCE_SEPARATOR}#{data[:source]}"
+            end
+          else
+            value = data
+          end
 
-          @aggregated[k] ||= Aggregate.new
-          @aggregated[k] << value
+          @aggregated[metric] ||= Aggregate.new
+          @aggregated[metric] << value
         end
         autosubmit_check
         self
@@ -38,25 +47,32 @@ module Librato
 
       # Remove all queued metrics
       #
-      def flush
+      def clear
         @aggregated = {}
       end
-      alias :clear :flush
+      alias :flush :clear
 
       def queued
         gauges = []
 
-        @aggregated.each do |k,v|
-          gauges << {
-            :name => k.to_s,
-            :count => v.count,
-            :sum => v.sum,
+        @aggregated.each do |metric, data|
+          source = nil
+          metric = metric.to_s
+          if metric.include?(SOURCE_SEPARATOR)
+            metric, source = metric.split(SOURCE_SEPARATOR)
+          end
+          entry = {
+            :name => metric,
+            :count => data.count,
+            :sum => data.sum,
 
             # TODO: make float/non-float consistent in the gem
-            :min => v.min.to_f,
-            :max => v.max.to_f
+            :min => data.min.to_f,
+            :max => data.max.to_f
             # TODO: expose v.sum2 and include
           }
+          entry[:source] = source if source
+          gauges << entry
         end
 
         req = { :gauges => gauges }

data/lib/librato/metrics/client.rb

@@ -60,6 +60,19 @@ module Librato
         @connection ||= Connection.new(:client => self, :api_endpoint => api_endpoint)
       end
       
+      # Overrride user agent for this client's connections. If you
+      # are trying to specify an agent identifier for developer
+      # program, see #agent_identifier.
+      #
+      def custom_user_agent=(agent)
+        @user_agent = agent
+        @connection = nil
+      end
+      
+      def custom_user_agent
+        @user_agent
+      end
+      
       # Completely delete metrics with the given names. Be
       # careful with this, this is instant and permanent.
       #
@@ -91,7 +104,7 @@ module Librato
       #
       # @example Get 20 most recent data points for a specific source
       #   data = Librato::Metrics.fetch :temperature, :count => 20,
-      #                                  :source => 'app1'
+      #                                 :source => 'app1'
       #
       # @example Get the 20 most recent 15 minute data point rollups
       #   data = Librato::Metrics.fetch :temperature, :count => 20,
@@ -172,7 +185,7 @@ module Librato
 
       # Set persistence type to use when saving metrics.
       #
-      # @param [Symbol] persistence_type
+      # @param [Symbol] persist_method
       def persistence=(persist_method)
         @persistence = persist_method
       end
@@ -185,10 +198,27 @@ module Librato
       # Submit all queued metrics.
       #
       def submit(args)
-        @queue ||= Queue.new(:client => self, :skip_measurement_times => true)
+        @queue ||= Queue.new(:client => self, 
+                             :skip_measurement_times => true, 
+                             :clear_failures => true)
         @queue.add args
         @queue.submit
       end
+      
+      # Update metric with the given name.
+      #
+      # @example Update metric 'temperature'
+      #   Librato::Metrics.update :temperature, :period => 15, :attributes => { :color => 'F00' }
+      #
+      # @example Update metric 'humidity', creating it if it doesn't exist
+      #   Librato::Metrics.update 'humidity', :type => :gauge, :period => 60, :display_name => 'Humidity'
+      #
+      def update(metric, options = {})
+        connection.put do |request|
+          request.url connection.build_url("metrics/#{metric}")
+          request.body = MultiJson.dump(options)
+        end
+      end
 
     private
 

data/lib/librato/metrics/connection.rb

@@ -48,6 +48,7 @@ module Librato
       # User-agent used when making requests.
       #
       def user_agent
+        return @client.custom_user_agent if @client.custom_user_agent
         ua_chunks = []
         agent_identifier = @client.agent_identifier
         if agent_identifier && !agent_identifier.empty?

data/lib/librato/metrics/errors.rb

@@ -9,6 +9,7 @@ module Librato
     class NoMetricsProvided < MetricsError; end
     class NoClientProvided < MetricsError; end
     class InvalidMeasureTime < MetricsError; end
+    class NotMergeable < MetricsError; end
     
     class NetworkError < StandardError; end
     

data/lib/librato/metrics/processor.rb

@@ -30,16 +30,20 @@ module Librato
         options = {:per_request => @per_request}
         if persister.persist(self.client, self.queued, options)
           @last_submit_time = Time.now
-          flush and return true
+          clear and return true
         end
         false
+      rescue ClientError
+        # clean up if we hit exceptions if asked to
+        clear if @clear_on_failure
+        raise
       end
       
       # Capture execution time for a block and queue
       # it as the value for a metric. Times are recorded
       # in milliseconds.
       #
-      # Options are the same as for {#add}.
+      # Options are the same as for #add.
       #
       # @example Queue API request response time
       #   queue.time :api_request_time do
@@ -79,6 +83,7 @@ module Librato
         @per_request = options[:per_request] || MEASUREMENTS_PER_REQUEST
         @source = options[:source]
         @create_time = Time.now
+        @clear_on_failure = options[:clear_failures] || false
       end
       
       def autosubmit_check

data/lib/librato/metrics/queue.rb

@@ -16,10 +16,10 @@ module Librato
 
       # Add a metric entry to the metric set:
       #
-      # @param Hash metrics metrics to add
-      # @return Queue returns self
-      def add(args)
-        args.each do |key, value|
+      # @param [Hash] measurements measurements to add
+      # @return [Queue] returns self
+      def add(measurements)
+        measurements.each do |key, value|
           if value.respond_to?(:each)
             metric = value
             metric[:name] = key.to_s
@@ -57,11 +57,10 @@ module Librato
 
       # Remove all queued metrics
       #
-      def flush
+      def clear
         @queued = {}
       end
-      alias :clear :flush
-      alias :flush_queued :flush
+      alias :flush :clear
 
       # Currently queued gauges
       #
@@ -69,6 +68,35 @@ module Librato
       def gauges
         @queued[:gauges] || []
       end
+      
+      # Combines queueable measures from the given object
+      # into this queue.
+      #
+      # @example Merging queues for more performant submission
+      #   queue1.merge!(queue2)
+      #   queue1.submit  # submits combined contents
+      #
+      # @return self
+      def merge!(mergeable)
+        if mergeable.respond_to?(:queued)
+          to_merge = mergeable.queued
+        elsif mergeable.respond_to?(:has_key?)
+          to_merge = mergeable
+        else
+          raise NotMergeable
+        end
+        Metrics::PLURAL_TYPES.each do |type|
+          if to_merge[type]
+            measurements = reconcile_source(to_merge[type], to_merge[:source])
+            if @queued[type]
+              @queued[type] += measurements
+            else
+              @queued[type] = measurements
+            end
+          end
+        end
+        self
+      end
 
       # All currently queued metrics
       #
@@ -96,6 +124,17 @@ module Librato
         end
       end
     
+      def reconcile_source(measurements, source)
+        return measurements if !source || source == @source
+        measurements.map! do |measurement|
+          unless measurement[:source]
+            measurement[:source] = source
+          end
+          measurement
+        end
+        measurements
+      end
+    
       def submit_check
         autosubmit_check # in Processor
         if @autosubmit_count && self.length >= @autosubmit_count

data/lib/librato/metrics/version.rb

@@ -1,5 +1,5 @@
 module Librato
   module Metrics
-    VERSION = "0.6.1"
+    VERSION = "0.7.0"
   end
 end

data/spec/integration/metrics_spec.rb

@@ -150,8 +150,69 @@ module Librato
           data['baz'][0]['value'] == 456.0
         end
       end
+      
+      it "should not retain errors" do
+        delete_all_metrics
+        Metrics.submit :foo => {:type => :counter, :value => 12}
+        lambda {
+          Metrics.submit :foo => 15 # submitting as gauge
+        }.should raise_error
+        lambda {
+          Metrics.submit :foo => {:type => :counter, :value => 17}
+        }.should_not raise_error
+      end
 
     end
+    
+    describe "#update" do
+      
+      context "with existing metric" do
+        before do
+          delete_all_metrics
+          Metrics.submit :foo => 123
+        end
+        
+        it "should upate the metric" do
+          Metrics.update :foo, :display_name => "Foo Metric",
+                               :period => 15,
+                               :attributes => {
+                                 :display_max => 1000
+                               }
+          foo = Metrics.fetch :foo
+          foo['display_name'].should == 'Foo Metric'
+          foo['period'].should == 15
+          foo['attributes'].should == {'display_max' => 1000}
+        end
+      end
+      
+      context "without an existing metric" do
+        it "should create the metric if type specified" do
+          delete_all_metrics
+          Metrics.update :foo, :display_name => "Foo Metric",
+                               :type => :gauge,
+                               :period => 15,
+                               :attributes => {
+                                 :display_max => 1000
+                               }
+          foo = Metrics.fetch :foo
+          foo['display_name'].should == 'Foo Metric'
+          foo['period'].should == 15
+          foo['attributes'].should == {'display_max' => 1000}
+        end
+        
+        it "should raise error if no type specified" do
+          delete_all_metrics
+          lambda {
+            Metrics.update :foo, :display_name => "Foo Metric",
+                                 :period => 15,
+                                 :attributes => {
+                                   :display_max => 1000
+                                 }
+          }.should raise_error
+        end
+      end
+      
+    end
 
   end
 end

data/spec/spec_helper.rb

@@ -70,9 +70,13 @@ end
 # @example
 #   {:foo => [1,3,2]}.should equal_unordered({:foo => [1,2,3]})
 RSpec::Matchers.define :equal_unordered do |result|
-  result.each { |key, value| result[key] = value.to_set }
+  result.each do |key, value|
+    result[key] = value.to_set if value.respond_to?(:to_set)
+  end
   match do |target|
-    target.each { |key, value| target[key] = value.to_set }
+    target.each do |key, value|
+      target[key] = value.to_set if value.respond_to?(:to_set)
+    end
     target == result
   end
 end

data/spec/unit/metrics/aggregator_spec.rb

@@ -76,6 +76,20 @@ module Librato
             }
             subject.queued.should equal_unordered(expected)
           end
+          
+          it "should respect source argument" do
+            subject.add :foo => {:source => 'alpha', :value => 1}
+            subject.add :foo => 5
+            subject.add :foo => {:source => :alpha, :value => 6}
+            subject.add :foo => 10
+            expected = { :gauges => [
+              { :name => 'foo', :source => 'alpha', :count => 2,
+                :sum => 7.0, :min => 1.0, :max => 6.0 },
+              { :name => 'foo', :count => 2, 
+                :sum => 15.0, :min => 5.0, :max => 10.0 }
+            ]}
+            subject.queued.should equal_unordered(expected)
+          end
         end
 
         context "with multiple hash arguments" do

data/spec/unit/metrics/connection_spec.rb

@@ -37,6 +37,15 @@ module Librato
           end
         end
         
+        context "with a custom user agent set" do
+          it "should use custom user agent" do
+            client = Client.new
+            client.custom_user_agent = 'foo agent'
+            connection = Connection.new(:client => client)
+            connection.user_agent.should == 'foo agent'
+          end
+        end
+        
         # TODO: verify user agent is being sent with rackup test
       end
       

data/spec/unit/metrics/queue_spec.rb

@@ -163,6 +163,101 @@ module Librato
         end
       end
       
+      describe "#merge!" do
+        context "with another queue" do
+          it "should merge gauges" do
+            q1 = Queue.new
+            q1.add :foo => 123, :bar => 456
+            q2 = Queue.new
+            q2.add :baz => 678
+            q2.merge!(q1)
+            expected = {:gauges=>[{:name=>"foo", :value=>123, :measure_time => @time},
+                                  {:name=>"bar", :value=>456, :measure_time => @time},
+                                  {:name=>"baz", :value=>678, :measure_time => @time}]}
+            q2.queued.should equal_unordered(expected)
+          end
+          
+          it "should merge counters" do
+            q1 = Queue.new
+            q1.add :users => {:type => :counter, :value => 1000}
+            q1.add :sales => {:type => :counter, :value => 250}
+            q2 = Queue.new
+            q2.add :signups => {:type => :counter, :value => 500}
+            q2.merge!(q1)
+            expected = {:counters=>[{:name=>"users", :value=>1000, :measure_time => @time},
+                                    {:name=>"sales", :value=>250, :measure_time => @time},
+                                    {:name=>"signups", :value=>500, :measure_time => @time}]}
+            q2.queued.should equal_unordered(expected)
+          end
+          
+          it "should maintain specified sources" do
+            q1 = Queue.new
+            q1.add :neo => {:source => 'matrix', :value => 123}
+            q2 = Queue.new(:source => 'red_pill')
+            q2.merge!(q1)
+            q2.queued[:gauges][0][:source].should == 'matrix'
+          end
+          
+          it "should not change default source" do
+            q1 = Queue.new(:source => 'matrix')
+            q1.add :neo => 456
+            q2 = Queue.new(:source => 'red_pill')
+            q2.merge!(q1)
+            q2.queued[:source].should == 'red_pill'
+          end
+          
+          it "should track previous default source" do
+            q1 = Queue.new(:source => 'matrix')
+            q1.add :neo => 456
+            q2 = Queue.new(:source => 'red_pill')
+            q2.add :morpheus => 678
+            q2.merge!(q1)
+            q2.queued[:gauges].each do |gauge|
+              if gauge[:name] == 'neo'
+                gauge[:source].should == 'matrix'
+              end
+            end
+          end
+          
+          it "should handle empty cases" do
+            q1 = Queue.new
+            q1.add :foo => 123, :users => {:type => :counter, :value => 1000}
+            q2 = Queue.new
+            q2.merge!(q1)
+            expected = {:counters => [{:name=>"users", :value=>1000, :measure_time => @time}],
+                        :gauges => [{:name=>"foo", :value=>123, :measure_time => @time}]}
+            q2.queued.should == expected
+          end
+        end
+        
+        context "with an aggregator" do
+          it "should merge" do
+            aggregator = Aggregator.new(:source => 'aggregator')
+            aggregator.add :timing => 102
+            aggregator.add :timing => 203
+            queue = Queue.new(:source => 'queue')
+            queue.add :gauge => 42
+            queue.merge!(aggregator)
+            expected = {:gauges=>[{:name=>"gauge", :value=>42, :measure_time=>@time}, 
+                                  {:name=>"timing", :count=>2, :sum=>305.0, :min=>102.0, :max=>203.0, :source=>"aggregator"}],
+                        :source=>'queue'}
+            queue.queued.should equal_unordered(expected)
+            
+          end
+        end
+        
+        context "with a hash" do
+          it "should merge" do
+            to_merge = {:gauges=>[{:name => 'foo', :value => 123}],
+                        :counters=>[{:name => 'bar', :value => 456}]}
+            q = Queue.new
+            q.merge!(to_merge)
+            q.gauges.length.should == 1
+            q.counters.length.should == 1
+          end
+        end
+      end
+      
       describe "#per_request" do
         it "should default to 500" do
           subject.per_request.should == 500

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: librato-metrics
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-11 00:00:00.000000000 Z
+date: 2012-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -163,6 +163,7 @@ extra_rdoc_files:
 - LICENSE
 files:
 - .gitignore
+- .rspec
 - .travis.yml
 - CHANGELOG.md
 - Gemfile
@@ -214,7 +215,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2003019020857888110
+      hash: -1999246465148166572
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: