restful_resource 1.4.1 → 1.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 709712fad9b584a11db8734c6de7c26ad6ae9060
-  data.tar.gz: 117d4d8d92144cf017c6e0bf5aa9e9f2ad96b31a
+  metadata.gz: 7ec89f5aff66263aa662e83535625118f92faad2
+  data.tar.gz: f8653d759998fb91a5ac0fdb52d340edb55beafd
 SHA512:
-  metadata.gz: c82a341ee0ba285b130399f5792b30f065555f3a7f9c1e94fa03b83675f36a06d6089bd6ebebeae5d54a6b0739f98a5cb041e1efca4abcea8b6ce145b04ee16a
-  data.tar.gz: f950b007bbc8087e31b9e5cebde0620d4f7967f0316cdc9fd4b55dad957d1142400580f37bfe5f3efa34745ae7066b4da6780784223f22f7068dbb3cb7407682
+  metadata.gz: 1f7050817b74a710234c0374aa388b4f3f3758ca9694ef49d89430894ae62a7edf0e375579556dc9978fac8d19075c204bc303cc82cb6a22d9c348343ab7ca57
+  data.tar.gz: 12bd9dc5305fc0b362dc94420ec6d7f55172203e775caf0dbeecdf242fb463275dab5f29d2c6656eb5e5d8c80b2eb3b1a221364918d50f3b604f92dad967a0d4

data/README.md

@@ -1,24 +1,76 @@
 # RestfulResource ![build status](https://circleci.com/gh/carwow/restful_resource.svg?style=shield&circle-token=0558310359000e8786d1fe42774b0e30b2b0e12c)
 
-TODO: Write a gem description
+Provides an ActiveResource like interface to JSON API's
 
-## Installation
+## Metrics
 
-Add this line to your application's Gemfile:
+### HTTP Metrics
 
-    gem 'restful_resource'
+Http requests are automatically instrumented using ActiveSupport::Notifications
 
-And then execute:
+A Metrics class can be provided that RestfulResource will use to emit metrics. This class needs to respond to `count, sample, measure` methods.
 
-    $ bundle
+eg
 
-Or install it yourself as:
+```
+RestfulResource::Base.configure(
+  base_url: "http://my.api.com/",
+  instrumentation: {
+    metric_class: Metrics,  # Required
+    app_name: 'rails_site', # Required
+    api_name: 'api'         # Optional, defaults to 'api'
+  }
+)
+```
 
-    $ gem install restful_resource
+Where the `Metrics` class has in interface like:
 
-## Usage
+```
+class Metrics
+  module_function
 
-TODO: Write usage instructions here
+  def count(name, i)
+  end
+
+  def sample(name, i)
+  end
+
+  def measure(name, i)
+  end
+end
+```
+
+This will call the methods on the Metrics class with:
+```
+Metrics.measure('rails_site.api.time', 215.161237) # Time taken
+Metrics.sample('rails_site.api.status', 200) # HTTP status code
+Metrics.count('rails_site.api.called, 1)
+```
+
+Note: To customize the names we can specify `:app_name` and `:api_name` options to `RestfulResource::Base.configure`
+
+### HTTP Cache Metrics
+
+Enable Http caching:
+
+```
+RestfulResource::Base.configure(
+  base_url: "http://my.api.com/",
+  cache_store: Rails.cache,
+  instrumentation: {
+    metric_class: Metrics,
+    app_name: 'rails_site',
+    api_name: 'api'
+  }
+)
+```
+
+This will call the methods on the Metrics class with:
+```
+Metrics.sample('rails_site.api.cache_hit', 1) # When a request is served from the cache
+Metrics.sample('rails_site.api.cache_miss', 1) # When a request is fetched from the remote API
+Metrics.sample('rails_site.api.cache_bypass', 1) # When a request did not go through the cache at all
+```
 
 ## Contributing
 

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'restful_resource'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require 'pry'
+# Pry.start
+
+require 'irb'
+IRB.start

data/lib/restful_resource/base.rb

@@ -6,14 +6,16 @@ module RestfulResource
                        username: nil,
                        password: nil,
                        logger: nil,
-                       cache_store: nil)
+                       cache_store: nil,
+                       instrumentation: {})
 
       @base_url = URI.parse(base_url)
 
       @http = RestfulResource::HttpClient.new(username: username,
                                               password: password,
                                               logger: logger,
-                                              cache_store: cache_store)
+                                              cache_store: cache_store,
+                                              instrumentation: instrumentation)
     end
 
     def self.resource_path(url)

data/lib/restful_resource/http_client.rb

@@ -52,9 +52,29 @@ module RestfulResource
       end
     end
 
-    def initialize(username: nil, password: nil, logger: nil, cache_store: nil, connection: nil)
+    def initialize(username: nil,
+                   password: nil,
+                   logger: nil,
+                   cache_store: nil,
+                   connection: nil,
+                   instrumentation: {})
+
+
+      api_name = instrumentation[:api_name]     ||= 'api'
+      instrumentation[:request_instrument_name] ||= "http.#{api_name}"
+      instrumentation[:cache_instrument_name]   ||= "http_cache.#{api_name}"
+
+      if instrumentation[:metric_class]
+        @metrics = Instrumentation.new(instrumentation.slice(:app_name, :api_name, :request_instrument_name, :cache_instrument_name, :metric_class))
+        @metrics.subscribe_to_notifications
+      end
+
       # Use a provided faraday client or initalize a new one
-      @connection = connection || initialize_connection(logger: logger, cache_store: cache_store)
+      @connection = connection || initialize_connection(logger: logger,
+                                                        cache_store: cache_store,
+                                                        instrumenter: ActiveSupport::Notifications,
+                                                        request_instrument_name: instrumentation.fetch(:request_instrument_name, nil),
+                                                        cache_instrument_name: instrumentation.fetch(:cache_instrument_name, nil))
 
       if username && password
         @connection.basic_auth username, password
@@ -79,7 +99,12 @@ module RestfulResource
 
     private
 
-    def initialize_connection(logger: nil, cache_store: nil)
+    def initialize_connection(logger: nil,
+                              cache_store: nil,
+                              instrumenter: nil,
+                              request_instrument_name: nil,
+                              cache_instrument_name: nil)
+
       @connection = Faraday.new do |b|
         b.request :url_encoded
         b.response :raise_error
@@ -89,7 +114,14 @@ module RestfulResource
         end
 
         if cache_store
-          b.use :http_cache, store: cache_store
+          b.use :http_cache, store: cache_store,
+                             logger: logger,
+                             instrumenter: instrumenter,
+                             instrument_name: cache_instrument_name
+        end
+
+        if instrumenter && request_instrument_name
+          b.use :instrumentation, name: request_instrument_name
         end
 
         b.response :encoding

data/lib/restful_resource/instrumentation.rb

@@ -0,0 +1,93 @@
+require 'active_support/notifications'
+
+module RestfulResource
+  class Instrumentation
+
+    def initialize(app_name:, api_name:, request_instrument_name:, cache_instrument_name:, metric_class:)
+      @app_name = app_name
+      @api_name = api_name
+      @request_instrument_name = request_instrument_name
+      @cache_instrument_name = cache_instrument_name
+      @metric_class = metric_class
+    end
+
+    attr_reader :app_name, :api_name, :request_instrument_name, :cache_instrument_name, :metric_class
+
+    def subscribe_to_notifications
+      validate_metric_class!
+
+      # Subscribes to events from Faraday
+      ActiveSupport::Notifications.subscribe request_instrument_name do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+
+        status = status_from_event(event)
+
+        # Outputs per API log lines like:
+        # measure#quotes_site.research_site_api.time=215.161237
+        # sample#quotes_site.research_site_api.status=200
+        # count#quotes_site.research_site_api.called=1
+        metric_class.measure cache_notifier_namespace(metric: 'time'), event.duration
+        metric_class.sample cache_notifier_namespace(metric: 'status'), status
+        metric_class.count cache_notifier_namespace(metric: 'called'), 1
+
+        # Outputs per resource log lines like:
+        # measure#quotes_site.research_site_api.api_v2_cap_derivatives.time=215.161237
+        # sample#quotes_site.research_site_api.api_v2_cap_derivatives.status=200
+        # count#quotes_site.research_site_api.api_v2_cap_derivatives.called=1
+        metric_class.measure cache_notifier_namespace(metric: 'time', event: event), event.duration
+        metric_class.sample cache_notifier_namespace(metric: 'status', event: event), status
+        metric_class.count cache_notifier_namespace(metric: 'called', event: event), 1
+      end
+
+      # Subscribes to events from Faraday::HttpCache
+      ActiveSupport::Notifications.subscribe cache_instrument_name do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        cache_status = event.payload[:cache_status]
+
+        # Outputs log lines like:
+        # sample#quotes_site.research_site_api.cache_hit=1
+        # sample#quotes_site.research_site_api.api_v2_cap_derivatives.cache_hit=1
+        case cache_status
+          when :fresh, :valid
+            metric_class.sample cache_notifier_namespace(metric: 'cache_hit'), 1
+            metric_class.sample cache_notifier_namespace(metric: 'cache_hit', event: event), 1
+          when :invalid, :miss
+            metric_class.sample cache_notifier_namespace(metric: 'cache_miss'), 1
+            metric_class.sample cache_notifier_namespace(metric: 'cache_miss', event: event), 1
+          when :unacceptable
+            metric_class.sample cache_notifier_namespace(metric: 'cache_bypass'), 1
+            metric_class.sample cache_notifier_namespace(metric: 'cache_bypass', event: event), 1
+        end
+      end
+    end
+
+    def validate_metric_class!
+      metric_methods = [:count, :sample, :measure]
+      if metric_methods.any? {|m| !metric_class.respond_to?(m) }
+        raise ArgumentError.new "Metric class '#{metric_class}' does not respond to #{metric_methods.join ','}"
+      end
+    end
+
+    def cache_notifier_namespace(event: nil, metric:)
+      [app_name, api_name, base_request_path(event), metric].compact.join('.')
+    end
+
+    # Converts a path like "/api/v2/cap_derivatives/75423" to "api_v2_cap_derivatives"
+    def base_request_path(event)
+      path_from_event(event).split('/').drop(1).take(3).join('_') if event
+    end
+
+    def path_from_event(event)
+      url_from_event(event)&.path.to_s
+    end
+
+    def url_from_event(event)
+      event.payload[:env]&.url || event.payload&.url
+    end
+
+    def status_from_event(event)
+      event.payload[:env]&.status || event.payload&.status
+    end
+  end
+end
+

data/lib/restful_resource/version.rb

@@ -1,3 +1,3 @@
 module RestfulResource
-  VERSION = '1.4.1'
+  VERSION = '1.4.2'
 end

data/lib/restful_resource.rb

@@ -20,4 +20,5 @@ require_relative 'restful_resource/http_client'
 require_relative 'restful_resource/associations'
 require_relative 'restful_resource/rails_validations'
 require_relative 'restful_resource/redirections'
+require_relative 'restful_resource/instrumentation'
 require_relative 'restful_resource/base'

data/spec/restful_resource/http_client_configuration_spec.rb

@@ -40,6 +40,62 @@ describe RestfulResource::HttpClient do
         expect(middleware).to include FaradayMiddleware::Gzip
       end
 
+      describe 'instrumentation' do
+        context 'with the default key' do
+          it 'uses default instrumenter and key' do
+            expect(find_middleware_args(connection, 'FaradayMiddleware::Instrumentation')).to include(name: 'http.api')
+          end
+        end
+
+        context 'with an api_name' do
+          let(:connection) { described_class.new(instrumentation: { api_name: 'my_api_name'}).instance_variable_get("@connection") }
+
+          it 'uses default instrumenter with the api_name' do
+            expect(find_middleware_args(connection, 'FaradayMiddleware::Instrumentation')).to include(name: 'http.my_api_name')
+          end
+        end
+
+        context 'with a custom instrumentation key' do
+          let(:connection) { described_class.new(instrumentation: { request_instrument_name: 'foo.bar'}).instance_variable_get("@connection") }
+
+          it 'uses default instrumenter with the custom key' do
+            expect(find_middleware_args(connection, 'FaradayMiddleware::Instrumentation')).to include(name: 'foo.bar')
+          end
+        end
+
+        context 'with a given Metrics class' do
+          class FakeMetrics
+            def count(name, value); end
+            def sample(name, value); end
+            def measure(name, value); end
+          end
+
+          let(:mock_instrumention) { instance_double(RestfulResource::Instrumentation) }
+
+          before do
+            allow(RestfulResource::Instrumentation).to receive(:new).and_return mock_instrumention
+            allow(mock_instrumention).to receive(:subscribe_to_notifications)
+          end
+
+          it 'initializes the Instrumentation' do
+            described_class.new(instrumentation: { app_name: 'rails', api_name: 'api', metric_class: FakeMetrics})
+
+            expect(RestfulResource::Instrumentation).to have_received(:new)
+                                               .with(app_name: 'rails',
+                                                     api_name: 'api',
+                                                     request_instrument_name: 'http.api',
+                                                     cache_instrument_name: 'http_cache.api',
+                                                     metric_class: FakeMetrics)
+          end
+
+          it 'subscribes to the notifications' do
+            described_class.new(instrumentation: { app_name: 'rails', api_name: 'api', metric_class: FakeMetrics})
+
+            expect(mock_instrumention).to have_received(:subscribe_to_notifications)
+          end
+        end
+      end
+
       describe 'when provided a logger' do
         let(:connection) { described_class.new(logger: logger).instance_variable_get("@connection") }
         let(:logger) { Logger.new('/dev/null') }
@@ -63,6 +119,22 @@ describe RestfulResource::HttpClient do
         it 'uses that cache_store' do
           expect(find_middleware_args(connection, 'Faraday::HttpCache')).to include(store: 'redis')
         end
+
+        context 'and an api_name is provided' do
+          let(:connection) { described_class.new(cache_store: 'redis', instrumentation: { api_name: 'my_api_name'}).instance_variable_get("@connection") }
+
+          it 'passes the instrumenter and the api_name' do
+            expect(find_middleware_args(connection, 'Faraday::HttpCache')).to include(instrumenter: ActiveSupport::Notifications, instrument_name: 'http_cache.my_api_name')
+          end
+        end
+
+        context 'and a custom instrument name is provided' do
+          let(:connection) { described_class.new(cache_store: 'redis', instrumentation: { cache_instrument_name: 'foo.bar'}).instance_variable_get("@connection") }
+
+          it 'passes the instrumenter to the http cache middleware' do
+            expect(find_middleware_args(connection, 'Faraday::HttpCache')).to include(instrumenter: ActiveSupport::Notifications, instrument_name: 'foo.bar')
+          end
+        end
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: restful_resource
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.4.2
 platform: ruby
 authors:
 - David Santoro
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-13 00:00:00.000000000 Z
+date: 2017-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -169,7 +169,8 @@ description: A simple activerecord inspired rest resource base class implemented
   rest-client
 email:
 - developers@carwow.co.uk
-executables: []
+executables:
+- console
 extensions: []
 extra_rdoc_files: []
 files:
@@ -178,12 +179,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/console
 - circle.yml
 - lib/restful_resource.rb
 - lib/restful_resource/associations.rb
 - lib/restful_resource/authorization.rb
 - lib/restful_resource/base.rb
 - lib/restful_resource/http_client.rb
+- lib/restful_resource/instrumentation.rb
 - lib/restful_resource/null_logger.rb
 - lib/restful_resource/open_object.rb
 - lib/restful_resource/paginated_array.rb