librato-metrics 0.3.1 → 0.4.0

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Changelog
 
+### Version 0.4.0
+* Add ability to set agent_identifier for use with developer program (Sean Porter)
+* Documentation improvements
+
 ### Version 0.3.1
 * Upgrade excon to 0.9.5 to fix intermittent socket errors
 

data/README.md

@@ -125,7 +125,7 @@ This is an early release and as such is lacking some capabilities slated for fut
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
 * Fork the project and submit a pull request from a feature or bugfix branch.
 * Please include specs. This is important so we don't break your changes unintentionally in a future version.
-* Please don't modify the Rakefile, version, or history. If you do change these files, please isolate a separate commit so we can cherry-pick around it.
+* Please don't modify the gemspec, Rakefile, version, or changelog. If you do change these files, please isolate a separate commit so we can cherry-pick around it.
 
 ## Copyright
 

data/lib/librato/metrics.rb

@@ -26,9 +26,9 @@ module Librato
     # Expose class methods of Simple via Metrics itself.
     #
     # TODO: Explain exposed interface with examples.
-    def_delegators Librato::Metrics::Simple, :api_endpoint, :api_endpoint=,
-                  :authenticate, :connection, :persistence, :persistence=,
-                  :persister, :submit
+    def_delegators Librato::Metrics::Simple, :agent_identifier, :api_endpoint,
+                  :api_endpoint=, :authenticate, :connection, :persistence,
+                  :persistence=, :persister, :submit
 
     # Query metric data
     #

data/lib/librato/metrics/errors.rb

@@ -5,6 +5,7 @@ module Librato
     class MetricsError < StandardError; end
 
     class CredentialsMissing < MetricsError; end
+    class AgentInfoMissing < MetricsError; end
     class NoMetricsQueued < MetricsError; end
 
   end

data/lib/librato/metrics/simple.rb

@@ -17,6 +17,28 @@ module Librato
         # class instance vars
         attr_accessor :email, :api_key
 
+        # Provide agent identifier for the developer program. See:
+        # http://support.metrics.librato.com/knowledgebase/articles/53548-developer-program
+        #
+        # @example Have the gem build your identifier string
+        #   Librato::Metrics.agent_identifier 'flintstone', '0.5', 'fred'
+        #
+        # @example Provide your own identifier string
+        #   Librato::Metrics.agent_identifier 'flintstone/0.5 (dev_id:fred)'
+        #
+        # @example Remove identifier string
+        #   Librato::Metrics.agent_identifier ''
+        def agent_identifier(*args)
+          if args.length == 1
+            @agent_identifier = args.first
+          elsif args.length == 3
+            @agent_identifier = "#{args[0]}/#{args[1]} (dev_id:#{args[2]})"
+          elsif ![0,1,3].include?(args.length)
+            raise ArgumentError, 'invalid arguments, see method documentation'
+          end
+          @agent_identifier ||= ''
+        end
+
         # API endpoint to use for queries and direct
         # persistence.
         #
@@ -71,11 +93,12 @@ module Librato
           @persistence = persist_method
         end
 
+        # Current persister object.
         def persister
           @queue ? @queue.persister : nil
         end
 
-        # Submit all queued metrics
+        # Submit all queued metrics.
         #
         def submit(args)
           @queue ||= Queue.new(:skip_measurement_times => true)
@@ -83,9 +106,17 @@ module Librato
           @queue.submit
         end
 
+        # User-agent used when making requests.
+        #
         def user_agent
-          ruby_ver = "#{ruby_engine}; #{RUBY_VERSION}p#{RUBY_PATCHLEVEL}; #{RUBY_PLATFORM}"
-          "librato-metrics/#{Metrics::VERSION} (#{ruby_ver}) direct-excon/#{Excon::VERSION}"
+          ua_chunks = []
+          if agent_identifier && !agent_identifier.empty?
+            ua_chunks << agent_identifier
+          end
+          ua_chunks << "librato-metrics/#{Metrics::VERSION}"
+          ua_chunks << "(#{ruby_engine}; #{RUBY_VERSION}p#{RUBY_PATCHLEVEL}; #{RUBY_PLATFORM})"
+          ua_chunks << "direct-excon/#{Excon::VERSION}"
+          ua_chunks.join(' ')
         end
 
       private

data/lib/librato/metrics/version.rb

@@ -1,5 +1,5 @@
 module Librato
   module Metrics
-    VERSION = "0.3.1"
+    VERSION = "0.4.0"
   end
 end

data/spec/spec_helper.rb

@@ -26,4 +26,13 @@ RSpec.configure do |config|
     end
   end
 
+end
+
+# Ex: 'foobar'.should start_with('foo') #=> true
+#
+RSpec::Matchers.define :start_with do |start_string|
+  match do |string|
+    start_length = start_string.length
+    string[0..start_length-1] == start_string
+  end
 end

data/spec/unit/metrics/simple_spec.rb

@@ -5,6 +5,35 @@ module Librato
 
     describe Simple do
 
+      describe "#agent_identifier" do
+        context "when given a single string argument" do
+          it "should set agent_identifier" do
+            Simple.agent_identifier 'mycollector/0.1 (dev_id:foo)'
+            Simple.agent_identifier.should == 'mycollector/0.1 (dev_id:foo)'
+          end
+        end
+
+        context "when given three arguments" do
+          it "should compose an agent string" do
+            Simple.agent_identifier('test_app', '0.5', 'foobar')
+            Simple.agent_identifier.should == 'test_app/0.5 (dev_id:foobar)'
+          end
+
+          context "when given an empty string" do
+            it "should set to empty" do
+              Simple.agent_identifier ''
+              Simple.agent_identifier.should == ''
+            end
+          end
+        end
+
+        context "when given two arguments" do
+          it "should raise error" do
+            lambda { Simple.agent_identifier('test_app', '0.5') }.should raise_error(ArgumentError)
+          end
+        end
+      end
+
       describe "#api_endpoint" do
         it "should default to metrics" do
           Simple.api_endpoint.should == 'https://metrics-api.librato.com/v1/'
@@ -75,7 +104,23 @@ module Librato
         end
       end
 
+      describe "#user_agent" do
+        context "without an agent_identifier" do
+          it "should render standard string" do
+            Simple.agent_identifier('')
+            Simple.user_agent.should start_with('librato-metrics')
+          end
+        end
+
+        context "with an agent_identifier" do
+          it "should render agent_identifier first" do
+            Simple.agent_identifier('foo', '0.5', 'bar')
+            Simple.user_agent.should start_with('foo/0.5')
+          end
+        end
+      end
+
     end
 
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: librato-metrics
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-22 00:00:00.000000000Z
+date: 2012-03-06 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
-  requirement: &70150070015400 !ruby/object:Gem::Requirement
+  requirement: &70302139720560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 0.9.5
   type: :runtime
   prerelease: false
-  version_requirements: *70150070015400
+  version_requirements: *70302139720560
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &70150070014820 !ruby/object:Gem::Requirement
+  requirement: &70302139720160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70150070014820
+  version_requirements: *70302139720160
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70150070014120 !ruby/object:Gem::Requirement
+  requirement: &70302139719700 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70150070014120
+  version_requirements: *70302139719700
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70150070013420 !ruby/object:Gem::Requirement
+  requirement: &70302139719200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: 2.6.0
   type: :development
   prerelease: false
-  version_requirements: *70150070013420
+  version_requirements: *70302139719200
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70150070012920 !ruby/object:Gem::Requirement
+  requirement: &70302139718780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70150070012920
+  version_requirements: *70302139718780
 - !ruby/object:Gem::Dependency
   name: rdiscount
-  requirement: &70150070012160 !ruby/object:Gem::Requirement
+  requirement: &70302139718320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,7 +76,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70150070012160
+  version_requirements: *70302139718320
 description: An easy to use ruby wrapper for Librato's Metrics API
 email: matt@librato.com
 executables: []
@@ -127,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.12
+rubygems_version: 1.8.16
 signing_key: 
 specification_version: 2
 summary: Ruby wrapper for Librato's Metrics API