rate_throttle_client 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a98e4aae0d6770a20d784d63888ac487ad537bc27c2cb00127498a4afd41fb20
-  data.tar.gz: 9c6b04db20202345cbe2c9995c09fbd3b1f79521e5c33d5337851f0c93455d5e
+  metadata.gz: b93186de79a4c1b41605182c30ba093f37b569e1d44a23e6d9dbd7b634827f4e
+  data.tar.gz: 034a009ee78065955c40fe0b5da17c9384deefc961bff812b7b2c61fe2086219
 SHA512:
-  metadata.gz: 5a32f254cb2c857c4e50cf83fdbece7e9c60c8031f9ffa1d5957e7778899e68e2ccc4565cf6a6cc96ef685a8af05681527de61ea7b0c80ac59077e904850b88a
-  data.tar.gz: 8a8e0cd1b0809ff00c51c2bd986e4f270a054c6ae1f99ef67ef2634b0e2cb8c659bb02727f9179c9767ad4bc22d3bd28f84333f559d140404b44ab93d0db3012
+  metadata.gz: 0d10866abfcd48e216bbb11cb7bb40c15711bb9b190ae914073877f552ea5845d969b2b59452ec06fdf1575a6b78065e7a0139e15928b31a7555715b4e26c161
+  data.tar.gz: 96e51b05c20faab8d552d9465f0b914dfac5ae3451cfec48ebec3039e2719ab74386db34af43245a3234ba84a04940e150a06d4b10b8752437868bfa814ac54f

data/.circleci/config.yml

@@ -4,6 +4,12 @@ references:
     run:
       name: Run test suite
       command: bundle exec rake
+  imagick: &imagick
+    run:
+      name: Image Magick
+      command: |
+        sudo apt-get update
+        sudo apt-get install -y imagemagick ghostscript
   restore: &restore
     restore_cache:
       keys:
@@ -21,11 +27,21 @@ references:
         - ./vendor/bundle
       key: v1-dependencies-{{ checksum "Gemfile.lock" }}
 jobs:
+  "ruby-2.2":
+    docker:
+      - image: circleci/ruby:2.5
+    steps:
+      - checkout
+      - <<: *imagick
+      - <<: *bundle
+      - <<: *save
+      - <<: *unit
   "ruby-2.3":
     docker:
       - image: circleci/ruby:2.5
     steps:
       - checkout
+      - <<: *imagick
       - <<: *bundle
       - <<: *save
       - <<: *unit
@@ -34,6 +50,7 @@ jobs:
       - image: circleci/ruby:2.5
     steps:
       - checkout
+      - <<: *imagick
       - <<: *bundle
       - <<: *save
       - <<: *unit
@@ -42,6 +59,7 @@ jobs:
       - image: circleci/ruby:2.5
     steps:
       - checkout
+      - <<: *imagick
       - <<: *bundle
       - <<: *save
       - <<: *unit
@@ -50,6 +68,7 @@ jobs:
       - image: circleci/ruby:2.6
     steps:
       - checkout
+      - <<: *imagick
       - <<: *bundle
       - <<: *save
       - <<: *unit
@@ -58,6 +77,7 @@ jobs:
       - image: circleci/ruby:2.7
     steps:
       - checkout
+      - <<: *imagick
       - <<: *bundle
       - <<: *save
       - <<: *unit
@@ -66,6 +86,7 @@ jobs:
       - image: circleci/jruby:latest
     steps:
       - checkout
+      - <<: *imagick
       - <<: *bundle
       - <<: *save
       - <<: *unit
@@ -74,6 +95,7 @@ workflows:
   version: 2
   build:
     jobs:
+      - "ruby-2.2"
       - "ruby-2.3"
       - "ruby-2.4"
       - "ruby-2.5"

data/.gitignore

@@ -9,4 +9,6 @@ Gemfile.lock
 /spec/reports/
 /tmp/
 
+test/fixtures/logs/prop_dec/chart.png
+
 logs/*/**

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Master (Unreleased)
 
+## 0.1.1
+
+- Supports Ruby 2.2
+- Chart support
+
 ## 0.1.0
 
 - First

data/README.md

@@ -1,6 +1,6 @@
 # RateThrottleClient
 
-Rate limiting is for servers, rate throttling is for clients. This library implements a number of strategies for handling rate throttling on the client and a methodology for comparing performance of those clients in simulated environments. Essentially, we don't just give you the code to rate throttle, we also give you the information to help you figure out the best strategy to rate throttle as well.
+Rate limiting is for servers, rate throttling is for clients. This library implements a number of strategies for handling rate throttling on the client and a methodology for comparing performance of those clients. We don't just give you the code to rate throttle, we also give you the information to help you figure out the best strategy to rate throttle as well.
 
 ## Installation
 
@@ -32,14 +32,16 @@ end
 
 If the server returns a `429` status (the HTTP code indicating that a server side rate limit has been reached) then the request will be retried according to the classes' strategy.
 
-If you're not using Excon to build your API client, then you'll need to make sure the object returned to the block responds to `status` (returning the status code) and a `headers` method.
+## Expected return value from call
+
+If you're not using Excon to build your API client, then you'll need to make sure the object returned to the block responds to `status` (returning the status code). To use `ExponentialIncreaseProportionalRemainingDecrease` it's expected that `headers["RateLimit-Remaining"].to_i` returns the number of available requests capacity.
 
 ### Config
 
 ```ruby
 RateThrottleClient.config do |config|
-  config.log_block = ->(info){ puts "I get called when rate limiting is triggered #{info.sleep_for} #{info.request}" }
-  config.max_limit = 4500.to_f # Maximum number of requests per hour
+  config.log_block = ->(info){ puts "I get called when rate throttling is triggered #{info.sleep_for} #{info.request}" }
+  config.max_limit = 4500.to_f # Maximum number of requests available
   config.multiplier = 1.2 # When rate limiting happens, this is amount to the sleep value is increased by
 end
 ```
@@ -53,19 +55,22 @@ This library has a few strategies you can choose between:
 - RateThrottleClient::ExponentialIncreaseProportionalDecrease
 - RateThrottleClient::ExponentialIncreaseProportionalRemainingDecrease
 
-To choose, you need to understand what makes a "good" throttling algorithm, and then you need some benchmarks.
+To choose, you need to understand what makes a "good" throttling strategy, and then you need some benchmarks.
 
 ## What Makes a Good Rate Throttle strategy?
 
-- Minimize retry ratio: For example if every 50 successful requests, the client hits a rate limited request the ratio of retries is 1/50 or 2%. Why minimize this value? It takes CPU and Network resources to make requests that fail, if the client is making requests that are being limited, it's using resources that could be better spent somewhere else. The server also benefits as it spends less time dealing with rate limiting.
-- Minimize standard deviation of request count across the system: If there are two clients and one client is throttling by sleeping for 100 seconds and the other is throttling for 1 second, the distribution of requests are not equitable. Ideally over time each client might go up or down, but both would see a median of 50 seconds of sleep time. Why? If processes in a system have a high variance, one process is starved for API resources. It then becomes difficult to balance or optimize otherworkloads. When a client is stuck waiting on the API, ideally it can perform other operations (for example in other threads). If one process is using 100% of CPU and slamming the API and other is using 1% of CPU and barely touching the API, it is difficult to balance the workloads.
-- Minimize sleep/wait time: Retry ratio can be improved artificially by choosing high sleep times. In the real world consumers don't want to wait longer than absolutely necessarry. While a client might be able to "work steal" while it is sleeping/waiting, there's not guarantee that's the case. Essentially assume that any amount of time spent sleeping over the minimum amount of time required is wasted. This value is calculateable, but that calculation requires complete information of the distributed system.
-  - At high workload it should be able to consume all available requests: If a server allows 100,000 requests in a day then a client should be capable of making 100,000 requests. If the rate limiting algorithm only allows it to make 100 requests it would have low retry ratio but high wait time.
-  - Handle a change in work load to either slow down or speed up rate throttling: If the workload is light, then clients should not wait/sleep much. If workload is heavy, then clients should sleep/wait enough. The algorithm should adjust to a changing workload as quickly as possible.
+- Minimize retry ratio: For example if every 50 successful requests, the client hits a rate limited request the ratio of retries is 1/50 or 2%. Why minimize this value? It takes CPU and Network resources to make requests that fail, if the client is making requests that are being limited, it's using resources that could be better spent somewhere else. The server also benefits as it spends less time dealing with rate limiting. (Tracked via Avg retry rate)
+- Minimize standard deviation of request count across the system: If there are two clients and one client is throttling by sleeping for 100 seconds and the other is throttling for 1 second, the distribution of requests are not equitable. Ideally over time each client might go up or down, but both would see a median of 50 seconds of sleep time. Why? If processes in a system have a high variance, one process is starved for API resources. It then becomes difficult to balance or optimize otherworkloads. When a client is stuck waiting on the API, ideally it can perform other operations (for example in other threads). If one process is using 100% of CPU and slamming the API and other is using 1% of CPU and barely touching the API, it is difficult to balance the workloads. (Tracked via Stdev Request Count)
+- Minimize sleep/wait time: Retry ratio can be improved artificially by choosing high sleep times. In the real world consumers don't want to wait longer than absolutely necessarry. While a client might be able to "work steal" while it is sleeping/waiting, there's not guarantee that's the case. Essentially assume that any amount of time spent sleeping over the minimum amount of time required is wasted. This value is calculateable, but that calculation requires complete information of the distributed system. (Tracked via Max sleep time)
+  - At many available requests: It should be able to consume all available requests: If a server allows 100,000 requests in a day then a client should be capable of making 100,000 requests. If the rate limiting algorithm only allows it to make 100 requests it would have low retry ratio but high wait time.
+  - At few available requests: If clients do not sleep enough their retry rate will be very high, if they sleep too much then they they are not are using available resources.
+- Minimize time to respond to a change in available requests to either slow down or speed up rate throttling: A change can happen when clients are added or removed (for example if the number of servers/dynos are scaled up or down). It can also happen naturally if processing in a background worker or a web endpoint where the workload is cyclical. If there are few requests available and many become available, the rate throttle algorithm should adjust to match the new availability quickly. (Tracked via Time to clear workload)
+
+The only strategy that handles all these scenarios well is currently: `RateThrottleClient::ExponentialIncreaseProportionalRemainingDecrease` against a [GCRA rate limit strategy, such as the one implemented by the Heroku API]().
 
 ## Benchmarks
 
-These benchmarks are generated by running `rake bench` against the simulated "GCRA" rate limiting server. Which throttle strategy you use depends on your needs.
+These benchmarks are generated by running `rake bench` against the simulated "[GCRA](https://brandur.org/rate-limiting)" rate limiting server.
 
 **Lower values are better**
 
@@ -83,7 +88,7 @@ Raw request_counts: [1317.00, 1314.00, 1015.00, 963.00, 1254.00, 1133.00, 1334.0
 
 ```
 Time to clear workload (4500 requests, starting_sleep: 1s):
-76.18 seconds
+74.33 seconds
 ```
 
 ### RateThrottleClient::ExponentialIncreaseGradualDecrease results (duration: 30.0 minutes, multiplier: 1.2)
@@ -100,7 +105,7 @@ Raw request_counts: [48.00, 57.00, 56.00, 49.00, 282.00, 85.00, 83.00, 79.00, 28
 
 ```
 Time to clear workload (4500 requests, starting_sleep: 1s):
-65.50 seconds
+115.54 seconds
 ```
 
 ### RateThrottleClient::ExponentialIncreaseProportionalDecrease results (duration: 30.0 minutes, multiplier: 1.2)
@@ -117,7 +122,7 @@ Raw request_counts: [343.00, 123.00, 223.00, 144.00, 128.00, 348.00, 116.00, 383
 
 ```
 Time to clear workload (4500 requests, starting_sleep: 1s):
-489.24 seconds
+551.10 seconds
 ```
 
 ### RateThrottleClient::ExponentialIncreaseProportionalRemainingDecrease results (duration: 30.0 minutes, multiplier: 1.2)
@@ -134,7 +139,7 @@ Raw request_counts: [196.00, 269.00, 386.00, 302.00, 239.00, 197.00, 265.00, 150
 
 ```
 Time to clear workload (4500 requests, starting_sleep: 1s):
-66.92 seconds
+84.23 seconds
 ```
 
 ## Development

data/Rakefile

@@ -34,16 +34,18 @@ task :bench do
       demo.call
     ensure
       demo.print_results
+      demo.chart(true)
     end
 
     begin
       workload = 4500
       starting_sleep = 1
-      before_time = Time.now
       rackup_file = Pathname.new(__dir__).join("lib/rate_throttle_client/servers/decrease_only/config.ru")
 
       client = klass.new(starting_sleep_for: starting_sleep)
       demo = RateThrottleClient::Demo.new(client: client, time_scale: 10, starting_limit: 4500, duration: duration, remaining_stop_under: 10, rackup_file: rackup_file)
+
+      before_time = Time.now
       demo.call
       diff = Time.now - before_time
     ensure
@@ -56,3 +58,24 @@ task :bench do
     end
   end
 end
+
+task :charts do
+  duration = 30 * MINUTE
+  clients = [
+    RateThrottleClient::ExponentialBackoff,
+    RateThrottleClient::ExponentialIncreaseGradualDecrease,
+    RateThrottleClient::ExponentialIncreaseProportionalDecrease,
+    RateThrottleClient::ExponentialIncreaseProportionalRemainingDecrease
+  ]
+  clients.each do |klass|
+    begin
+      client = klass.new
+      demo = RateThrottleClient::Demo.new(client: client, duration: duration, time_scale: 10)
+      demo.call
+    ensure
+      demo.print_results
+      demo.chart
+    end
+  end
+end
+

data/lib/rate_throttle_client/chart.rb

@@ -0,0 +1,68 @@
+module RateThrottleClient
+  class Chart
+    def initialize(log_dir:, name:, time_scale:)
+      @log_dir = log_dir
+      @time_scale = time_scale
+      @name = name
+      @label_hash = nil
+      @log_files = nil
+    end
+
+    def log_files
+     @log_files ||= @log_dir.entries.map do |entry|
+        @log_dir.join(entry)
+      end.select do |file|
+        file.basename.to_s.end_with?("-chart-data.txt")
+      end
+    end
+
+    def get_line_count
+      log_files.first.each_line.count
+    end
+
+    def label_hash(line_count = get_line_count)
+      return @label_hash if @label_hash
+      @label_hash = {}
+
+      lines_per_hour = (3600.0 / @time_scale).floor
+
+      line_tick = (line_count / 5.0).floor
+
+      @label_hash[0] = "0"
+      1.upto(5).each do |i|
+        line_number = i * line_tick
+        @label_hash[line_number - 1] = "%.2f" % (line_number.to_f / lines_per_hour)
+      end
+
+      @label_hash
+    end
+
+    def call(open_file = false)
+      require 'gruff'
+
+      graph = Gruff::Line.new()
+      graph.title_font_size = 24
+
+      graph.hide_legend = true if log_files.length > 10
+      graph.title = "#{@name}\nSleep Values for #{log_files.count} clients"
+      graph.x_axis_label = "Time duration in hours"
+      graph.y_axis_label = "Sleep time in seconds"
+
+      log_files.each do |entry|
+        graph.data entry.basename.to_s.gsub("-chart-data.txt", ""), entry.each_line.map(&:to_f)
+      end
+
+      graph.labels = label_hash
+
+      graph.write(file)
+
+      `open #{file}` if open_file
+
+      file
+    end
+
+    def file
+      @log_dir.join('chart.png')
+    end
+  end
+end

data/lib/rate_throttle_client/demo.rb

@@ -7,6 +7,8 @@ require 'timecop'
 require 'wait_for_it'
 require 'enumerable/statistics'
 
+require_relative 'chart.rb'
+
 Thread.abort_on_exception = true
 
 # A class for simulating or "demoing" a rate throttle client
@@ -101,6 +103,11 @@ module RateThrottleClient
       io.puts "```"
     end
 
+    def chart(open_file)
+      chart = RateThrottleClient::Chart.new(log_dir: @log_dir, name: @client.class.to_s.gsub("RateThrottleClient::", ""), time_scale: @time_scale)
+      chart.call(open_file)
+    end
+
     def results
       result_hash = {}
 

data/lib/rate_throttle_client/version.rb

@@ -1,3 +1,3 @@
 module RateThrottleClient
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/rate_throttle_client.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.description   = %q{https://twitter.com/schneems/status/1138899094137651200}
   spec.homepage      = "https://github.com/zombocom/rate_throttle_client"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.2.0")
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/zombocom/rate_throttle_client"
@@ -30,5 +30,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "puma"
   spec.add_development_dependency "timecop"
   spec.add_development_dependency "excon"
+  spec.add_development_dependency "gruff"
   spec.add_development_dependency "enumerable-statistics"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rate_throttle_client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - schneems
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-11 00:00:00.000000000 Z
+date: 2020-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: wait_for_it
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: gruff
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: enumerable-statistics
   requirement: !ruby/object:Gem::Requirement
@@ -115,6 +129,7 @@ files:
 - bin/setup
 - lib/rate_throttle_client.rb
 - lib/rate_throttle_client/.DS_Store
+- lib/rate_throttle_client/chart.rb
 - lib/rate_throttle_client/clients/base.rb
 - lib/rate_throttle_client/clients/exponential_backoff.rb
 - lib/rate_throttle_client/clients/exponential_increase_gradual_decrease.rb
@@ -144,7 +159,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="