librato-metrics 0.4.3 → 0.5.0.pre1

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## Changelog
 
+### Version 0.5.0
+* Support using multiple accounts simultaneously via Client
+* Switch network library to faraday for broader platform support and flexibility
+* Automatic retry support
+* Consolidate connection functions in Connection
+* Documentation improvements
+
 ### Version 0.4.3
 * Bump excon to 0.13x to fix proxy support
 

data/README.md

@@ -107,6 +107,35 @@ 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.
 
+## Using Multiple Accounts Simultaneously
+
+If you need to use metrics with multiple sets of authentication credentials simultaneously, you can do it with `Client`:
+
+    joe = Librato::Metrics::Client.new
+    joe.authenticate 'email1', 'api_key1'
+    
+    mike = Librato::Metrics::Client.new
+    mike.authenticate 'email2', 'api_key2'
+
+All of the same operations you can call directly from `Librato::Metrics` are available per-client:
+
+	# list Joe's metrics
+	joe.list
+	
+	# fetch the last 20 data points for Mike's metric, humidity 
+	mike.fetch :humidity, :count => 20
+	
+There are two ways to associate a new queue with a client:
+
+	# these are functionally equivalent
+	joe_queue = Librato::Metrics::Queue.new(:client => joe)
+	joe_queue = joe.new_queue
+    
+Once the queue is associated you can use it normally:
+
+	joe_queue.add :temperature => {:source => 'sf', :value => 65.2}
+	joe_queue.submit
+
 ## Thread Safety
 
 The `librato-metrics` gem currently does not do internal locking for thread safety. When used in multi-threaded applications, please add your own mutexes for sensitive operations.

data/lib/librato/metrics/client.rb

@@ -0,0 +1,180 @@
+module Librato
+  module Metrics
+
+    class Client
+      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.
+      #
+      # @return [String] api_endpoint
+      def api_endpoint
+        @api_endpoint ||= 'https://metrics-api.librato.com'
+      end
+
+      # Set API endpoint for use with queries and direct
+      # persistence. Generally you should not need to set this
+      # as it will default to the current Librato Metrics
+      # endpoint.
+      #
+      def api_endpoint=(endpoint)
+        @api_endpoint = endpoint
+      end
+
+      # Authenticate for direct persistence
+      #
+      # @param [String] email
+      # @param [String] api_key
+      def authenticate(email, api_key)
+        flush_authentication
+        self.email, self.api_key = email, api_key
+      end
+
+      # Current connection object
+      #
+      def connection
+        # prevent successful creation if no credentials set
+        raise CredentialsMissing unless (self.email and self.api_key)
+        @connection ||= Connection.new(:client => self, :api_endpoint => api_endpoint)
+      end
+
+      # Query metric data
+      #
+      # @example Get attributes for a metric
+      #   attrs = Librato::Metrics.fetch :temperature
+      #
+      # @example Get 20 most recent data points for metric
+      #   data = Librato::Metrics.fetch :temperature, :count => 20
+      #
+      # @example Get 20 most recent data points for a specific source
+      #   data = Librato::Metrics.fetch :temperature, :count => 20,
+      #                                  :source => 'app1'
+      #
+      # @example Get the 20 most recent 15 minute data point rollups
+      #   data = Librato::Metrics.fetch :temperature, :count => 20,
+      #                                 :resolution => 900
+      #
+      # @example Get data points for the last hour
+      #   data = Librato::Metrics.fetch :start_time => Time.now-3600
+      #
+      # @example Get 15 min data points from two hours to an hour ago
+      #   data = Librato::Metrics.fetch :start_time => Time.now-7200,
+      #                                 :end_time => Time.now-3600,
+      #                                 :resolution => 900
+      #
+      # A full list of query parameters can be found in the API
+      # documentation: {http://dev.librato.com/v1/get/gauges/:name}
+      #
+      # @param [Symbol|String] metric Metric name
+      # @param [Hash] options Query options
+      def fetch(metric, options={})
+        query = options.dup
+        if query[:start_time].respond_to?(:year)
+          query[:start_time] = query[:start_time].to_i
+        end
+        if query[:end_time].respond_to?(:year)
+          query[:end_time] = query[:end_time].to_i
+        end
+        unless query.empty?
+          query[:resolution] ||= 1
+        end
+        # expects 200
+        url = connection.build_url("metrics/#{metric}", query)
+        response = connection.get(url)
+        parsed = MultiJson.decode(response.body)
+        # TODO: pagination support
+        query.empty? ? parsed : parsed["measurements"]
+      end
+
+      # Purge current credentials and connection.
+      #
+      def flush_authentication
+        self.email = nil
+        self.api_key = nil
+        @connection = nil
+      end
+
+      # List currently existing metrics
+      #
+      # @example List all metrics
+      #   Librato::Metrics.list
+      #
+      # @example List metrics with 'foo' in the name
+      #   Librato::Metrics.list :name => 'foo'
+      #
+      # @param [Hash] options
+      def list(options={})
+        query = {}
+        query[:name] = options[:name] if options[:name]
+        offset = 0
+        path = "metrics"
+        Collection.paginated_metrics(connection, path, query)
+      end
+
+      # Create a new queue which uses this client.
+      #
+      # @return [Queue]
+      def new_queue
+        Queue.new(:client => self)
+      end
+
+      # Persistence type to use when saving metrics.
+      # Default is :direct.
+      #
+      # @return [Symbol]
+      def persistence
+        @persistence ||= :direct
+      end
+
+      # Set persistence type to use when saving metrics.
+      #
+      # @param [Symbol] persistence_type
+      def persistence=(persist_method)
+        @persistence = persist_method
+      end
+
+      # Current persister object.
+      def persister
+        @queue ? @queue.persister : nil
+      end
+
+      # Submit all queued metrics.
+      #
+      def submit(args)
+        @queue ||= Queue.new(:client => self, :skip_measurement_times => true)
+        @queue.add args
+        @queue.submit
+      end
+
+    private
+
+      def flush_persistence
+        @persistence = nil
+      end
+
+    end
+
+  end
+end

data/lib/librato/metrics/{collect.rb → collection.rb}

@@ -1,6 +1,6 @@
 module Librato
   module Metrics
-    class Collect
+    class Collection
 
       MAX_RESULTS = 100
 
@@ -9,17 +9,19 @@ module Librato
       # @param [Excon] connection Connection to Metrics service
       # @param [String] path API uri
       # @param [Hash] query Query options
-      def self.paginated_metrics connection, path, query
+      def self.paginated_metrics(connection, path, query)
         results = []
-        response = connection.get(:path => path,
-                                  :query => query, :expects => 200)
+        # expects 200
+        url = connection.build_url(path, query)
+        response = connection.get(url)
         parsed = MultiJson.decode(response.body)
         results = parsed["metrics"]
         return results if parsed["query"]["found"] <= MAX_RESULTS
         query[:offset] = MAX_RESULTS
         begin
-          response = connection.get(:path => path,
-                                    :query => query, :expects => 200)
+          # expects 200
+          url = connection.build_url(path, query)
+          response = connection.get(url)
           parsed = MultiJson.decode(response.body)
           results.push(*parsed["metrics"])
           query[:offset] += MAX_RESULTS

data/lib/librato/metrics/connection.rb

@@ -0,0 +1,91 @@
+require 'faraday'
+require 'metrics/middleware/expects_status'
+require 'metrics/middleware/retry'
+
+module Librato
+  module Metrics
+    
+    class Connection
+      extend Forwardable
+      
+      DEFAULT_API_ENDPOINT = 'https://metrics-api.librato.com'      
+      
+      def_delegators :transport, :get, :post, :head, :put, :delete,
+                                 :build_url
+            
+      def initialize(options={})
+        @client = options[:client]
+        @api_endpoint = options[:api_endpoint]
+      end
+      
+      # API endpoint that will be used for requests.
+      #
+      def api_endpoint
+        @api_endpoint || DEFAULT_API_ENDPOINT
+      end
+      
+      def transport
+        raise NoClientProvided unless @client
+        @transport ||= Faraday::Connection.new(:url => api_endpoint + "/v1/") do |f|
+          #f.use FaradayMiddleware::EncodeJson
+          f.use Librato::Metrics::Middleware::Retry
+          f.use Librato::Metrics::Middleware::ExpectsStatus
+          #f.use FaradayMiddleware::ParseJson, :content_type => /\bjson$/
+          f.adapter Faraday.default_adapter
+        end.tap do |transport|
+          transport.headers[:user_agent] = user_agent
+          transport.headers[:content_type] = 'application/json'
+          transport.basic_auth @client.email, @client.api_key
+        end
+      end
+      
+      # User-agent used when making requests.
+      #
+      def user_agent
+        ua_chunks = []
+        agent_identifier = @client.agent_identifier
+        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-faraday/#{Faraday::VERSION}"
+        # TODO: include adapter information
+        #ua_chunks << "(#{transport_adapter})"
+        ua_chunks.join(' ')
+      end
+      
+    private
+
+      def adapter_version
+        adapter = transport_adapter
+        case adapter
+        when "NetHttp"
+          "Net::HTTP/#{Net::HTTP::Revision}"
+        when "Typhoeus"
+          "typhoeus/#{Typhoeus::VERSION}"
+        when "Excon"
+          "excon/#{Excon::VERSION}"
+        else
+          adapter
+        end
+      end
+
+      def ruby_engine
+        return RUBY_ENGINE if Object.constants.include?(:RUBY_ENGINE)
+        RUBY_DESCRIPTION.split[0]
+      end
+      
+      # figure out which adapter faraday is using
+      def transport_adapter
+        transport.builder.handlers.each do |handler|
+          if handler.name[0,16] == "Faraday::Adapter"
+            return handler.name[18..-1]
+          end 
+        end
+      end
+      
+    end
+    
+  end
+end

data/lib/librato/metrics/errors.rb

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

data/lib/librato/metrics/middleware/expects_status.rb

@@ -0,0 +1,22 @@
+module Librato
+  module Metrics
+    module Middleware
+      
+      class ExpectsStatus < Faraday::Response::Middleware
+        
+        def on_complete(env)
+          # TODO: clean up exception output
+          # TODO: catch specific status codes by request
+          case env[:status]
+          when 404
+            raise Faraday::Error::ResourceNotFound, env.to_s
+          when 400..600
+            raise Faraday::Error::ClientError, env.to_s
+          end
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/librato/metrics/middleware/retry.rb

@@ -0,0 +1,28 @@
+# borrowed from faraday 0.8, will use official once final
+module Librato
+  module Metrics
+    module Middleware
+      
+      class Retry < Faraday::Middleware
+        
+        def initialize(app, retries = 3)
+          @retries = retries
+          super(app)
+        end
+
+        def call(env)
+          retries = @retries
+          @app.call(env)
+        rescue StandardError, Timeout::Error
+          if retries > 0
+            retries -= 1
+            retry
+          end
+          raise
+        end
+        
+      end
+    
+    end
+  end
+end

data/lib/librato/metrics/persistence/direct.rb

@@ -9,11 +9,10 @@ module Librato
         # Persist the queued metrics directly to the
         # Metrics web API.
         #
-        def persist(queued)
+        def persist(client, queued)
           payload = MultiJson.encode(queued)
-          Simple.connection.post(:path => '/v1/metrics',
-              :headers => {'Content-Type' => 'application/json'},
-              :body => payload, :expects => 200)
+          # expects 200
+          client.connection.post('metrics', payload)
         end
 
       end

data/lib/librato/metrics/persistence/test.rb

@@ -6,7 +6,7 @@ module Librato
       class Test
 
         # persist the given metrics
-        def persist(metrics)
+        def persist(client, metrics)
           @persisted = metrics
           return !@return_value.nil? ? @return_value : true
         end

data/lib/librato/metrics/queue.rb

@@ -7,6 +7,7 @@ module Librato
       def initialize(options={})
         @queued ||= {}
         @skip_measurement_times = options.delete(:skip_measurement_times)
+        @client = options.delete(:client) || Librato::Metrics.client
       end
 
       # Add a metric entry to the metric set:
@@ -33,9 +34,19 @@ module Librato
         queued
       end
 
+      # The current Client instance this queue is using to authenticate
+      # and connect to Librato Metrics. This will default to the primary
+      # client used by the Librato::Metrics module unless it has been
+      # set to something else.
+      #
+      # @return [Librato::Metrics::Client]
+      def client
+        @client ||= Librato::Metrics.client
+      end
+
       # Currently queued counters
       #
-      # @return Array
+      # @return [Array]
       def counters
         @queued[:counters] || []
       end
@@ -88,7 +99,7 @@ module Librato
       # @return Boolean
       def submit
         raise NoMetricsQueued if self.queued.empty?
-        if persister.persist(self.queued)
+        if persister.persist(self.client, self.queued)
           flush and return true
         end
         false
@@ -124,7 +135,7 @@ module Librato
     private
 
       def create_persister
-        type = Simple.persistence.to_s.capitalize
+        type = self.client.persistence.to_s.capitalize
         Librato::Metrics::Persistence.const_get(type).new
       end
 

data/lib/librato/metrics/version.rb

@@ -1,5 +1,5 @@
 module Librato
   module Metrics
-    VERSION = "0.4.3"
+    VERSION = "0.5.0.pre1"
   end
 end

data/lib/librato/metrics.rb

@@ -2,22 +2,62 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 require 'base64'
-require 'excon'
 require 'multi_json'
 
+require 'metrics/client'
+require 'metrics/collection'
+require 'metrics/connection'
 require 'metrics/errors'
 require 'metrics/persistence'
 require 'metrics/queue'
-require 'metrics/simple'
 require 'metrics/version'
-require 'metrics/collect'
 
 module Librato
 
-  # Metrics provides a simple wrapper for the Metrics web API. Some
-  # of the methods Metrics provides will be documented below. Others
-  # are delegated to {Librato::Metrics::Simple} and will be
-  # documented there.
+  # Metrics provides a simple wrapper for the Metrics web API with a
+  # number of added conveniences for common use cases.
+  #
+  # See the {file:README.md README} for more information and examples.
+  #
+  # @example Simple use case
+  #   Librato::Metrics.authenticate 'email', 'api_key'
+  #
+  #   # list current metrics
+  #   Librato::Metrics.list
+  #
+  #   # submit a metric immediately
+  #   Librato::Metrics.submit :foo => 12712
+  #
+  #   # fetch the last 10 values of foo
+  #   Librato::Metrics.fetch :foo, :count => 10
+  #
+  # @example Queuing metrics for submission
+  #   queue = Librato::Metrics::Queue.new
+  #
+  #   # queue some metrics
+  #   queue.add :foo => 12312
+  #   queue.add :bar => 45678
+  #
+  #   # send the metrics
+  #   queue.submit
+  #
+  # @example Using a Client object
+  #   client = Librato::Metrics::Client.new
+  #   client.authenticate 'email', 'api_key'
+  #
+  #   # list client's metrics
+  #   client.list
+  #
+  #   # create an associated queue
+  #   queue = client.new_queue
+  #
+  #   # queue up some metrics and submit
+  #   queue.add :foo => 12345
+  #   queue.add :bar => 45678
+  #   queue.submit
+  #
+  # @note Most of the methods you can call directly on Librato::Metrics are
+  #   delegated to {Client} and are documented there.
   module Metrics
     extend SingleForwardable
 
@@ -25,73 +65,16 @@ module Librato
 
     # Expose class methods of Simple via Metrics itself.
     #
-    # TODO: Explain exposed interface with examples.
-    def_delegators Librato::Metrics::Simple, :agent_identifier, :api_endpoint,
-                  :api_endpoint=, :authenticate, :connection, :persistence,
-                  :persistence=, :persister, :submit
+    def_delegators :client, :agent_identifier, :api_endpoint,
+                   :api_endpoint=, :authenticate, :connection, :fetch,
+                   :list, :persistence, :persistence=, :persister, :submit
 
-    # Query metric data
+    # The Librato::Metrics::Client being used by module-level
+    # access.
     #
-    # @example Get attributes for a metric
-    #   attrs = Librato::Metrics.fetch :temperature
-    #
-    # @example Get 20 most recent data points for metric
-    #   data = Librato::Metrics.fetch :temperature, :count => 20
-    #
-    # @example Get 20 most recent data points for a specific source
-    #   data = Librato::Metrics.fetch :temperature, :count => 20,
-    #                                  :source => 'app1'
-    #
-    # @example Get the 20 most recent 15 minute data point rollups
-    #   data = Librato::Metrics.fetch :temperature, :count => 20,
-    #                                 :resolution => 900
-    #
-    # @example Get data points for the last hour
-    #   data = Librato::Metrics.fetch :start_time => Time.now-3600
-    #
-    # @example Get 15 min data points from two hours to an hour ago
-    #   data = Librato::Metrics.fetch :start_time => Time.now-7200,
-    #                                 :end_time => Time.now-3600,
-    #                                 :resolution => 900
-    #
-    # A full list of query parameters can be found in the API
-    # documentation: {http://dev.librato.com/v1/get/gauges/:name}
-    #
-    # @param [Symbol|String] metric Metric name
-    # @param [Hash] options Query options
-    def self.fetch(metric, options={})
-      query = options.dup
-      if query[:start_time].respond_to?(:year)
-        query[:start_time] = query[:start_time].to_i
-      end
-      if query[:end_time].respond_to?(:year)
-        query[:end_time] = query[:end_time].to_i
-      end
-      unless query.empty?
-        query[:resolution] ||= 1
-      end
-      response = connection.get(:path => "v1/metrics/#{metric}",
-                                :query => query, :expects => 200)
-      parsed = MultiJson.decode(response.body)
-      # TODO: pagination support
-      query.empty? ? parsed : parsed["measurements"]
-    end
-
-    # List currently existing metrics
-    #
-    # @example List all metrics
-    #   Librato::Metrics.list
-    #
-    # @example List metrics with 'foo' in the name
-    #   Librato::Metrics.list :name => 'foo'
-    #
-    # @param [Hash] options
-    def self.list(options={})
-      query = {}
-      query[:name] = options[:name] if options[:name]
-      offset = 0
-      path = "v1/metrics"
-      Collect.paginated_metrics connection, path, query
+    # @return [Client]
+    def self.client
+      @client ||= Librato::Metrics::Client.new
     end
 
   end

data/librato-metrics.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.rubygems_version = '1.3.5'
 
-  s.name              = 'librato-metrics'
-  s.version           = Librato::Metrics::VERSION
+  s.name        = 'librato-metrics'
+  s.version     = Librato::Metrics::VERSION
 
   s.summary     = "Ruby wrapper for Librato's Metrics API"
   s.description = "An easy to use ruby wrapper for Librato's Metrics API"
@@ -24,12 +24,13 @@ Gem::Specification.new do |s|
   s.extra_rdoc_files = %w[LICENSE]
 
   ## runtime dependencies
-  s.add_dependency 'excon', '~> 0.13.0'
+  s.add_dependency 'faraday', '~>0.7.6'
   s.add_dependency 'multi_json'
 
   ## development dependencies
   s.add_development_dependency 'rake'
   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
 

data/spec/integration/metrics/connection_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+module Librato
+  module Metrics
+   
+    describe Connection do
+      
+      # TODO: test retry support
+      # TODO: test status code support
+      
+    end
+    
+  end
+end