autotuner 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a0cbc0a71a4fe3322d56efe07228bc9e9f7abc0e63f5d6449d86bcc8d7e4475
-  data.tar.gz: a07a9184f3615a5e4da4a7d66ffae945e5da377e8cb089a0fcd1b40735c3d093
+  metadata.gz: 6aa488d0dd08183c2fb01c791f8c6348161e5c986ac3a77d2e70b395823330aa
+  data.tar.gz: 205b668f35e3abe8c52bd0cd84438dad052efa9d26432ec86b19170f0c487e3c
 SHA512:
-  metadata.gz: de54a820d1e5674b1a0b14d2519a2bd89e28f0d7d11690cf90e83a1ace67c829a2c9f019d4487952a4d2432146a857dce6905e82513273267ba7835beff2fcaa
-  data.tar.gz: fd56fb285f351006ac7091c24db412a96518d82771beebcbcbd16107d41e0a2a4af382b5ce2a3a719a21fb96aeea20bbd421e429eba568b3cd1d34a39ab58048
+  metadata.gz: 5bc44e43c8851f850dfc542b9004ebdcb3f446036d0064947006815867bb9a4ad9502d2db0dd41fcfdebd68bf100d359a1537ed81b9e5147d936e0219a1fa8c5
+  data.tar.gz: 706cc7f127c5004e6dc8473531b5a305809e6eab762481b3f0bbf48571668bd807d2388e4d2a621d63bdb1e0ca5972848b61175707a3b01b13888bb0bee885ba

data/.rubocop.yml

@@ -6,7 +6,6 @@ require: rubocop-minitest
 AllCops:
   NewCops: enable
   SuggestExtensions: false
-  TargetRubyVersion: 2.6
 
 Minitest/AssertInDelta:
   Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.3.0

data/Gemfile.lock

@@ -0,0 +1,59 @@
+PATH
+  remote: .
+  specs:
+    autotuner (1.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    json (2.7.1)
+    language_server-protocol (3.17.0.3)
+    minitest (5.22.3)
+    mocha (2.1.0)
+      ruby2_keywords (>= 0.0.5)
+    parallel (1.24.0)
+    parser (3.3.0.5)
+      ast (~> 2.4.1)
+      racc
+    racc (1.7.3)
+    rainbow (3.1.1)
+    rake (13.1.0)
+    regexp_parser (2.9.0)
+    rexml (3.2.6)
+    rubocop (1.62.1)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.31.2)
+      parser (>= 3.3.0.4)
+    rubocop-minitest (0.35.0)
+      rubocop (>= 1.61, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
+    rubocop-shopify (2.15.1)
+      rubocop (~> 1.51)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    unicode-display_width (2.5.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  autotuner!
+  minitest (~> 5.0)
+  mocha
+  rake (~> 13.0)
+  rubocop (~> 1.21)
+  rubocop-minitest
+  rubocop-shopify
+
+BUNDLED WITH
+   2.4.10

data/README.md

@@ -32,6 +32,9 @@ $ bundle add autotuner
    # This (optional) callback is called to provide metrics that can give you
    # insights about the performance of your app. It's recommended to send this
    # data to your observability service (e.g. Datadog, Prometheus, New Relic, etc).
+   # Use a metric type that would allow you to calculate the average and percentiles.
+   # On Datadog this would be the distribution type. On Prometheus this would be
+   # the histogram type.
    Autotuner.metrics_reporter = proc do |metrics|
      # stats is a hash of metric name (string) to integer value.
      metrics.each do |key, val|
@@ -61,11 +64,23 @@ While autotuner aims to comprehensively analyze your traffic to give the suggest
 ## Configuration
 
 - `Autotuner.enabled=`: (required, unless `Autotuner.sample_ratio` is set) Sets whether autotuner is enabled or not. When autotuner is disabled, data is not collected and suggestions are not given. Defaults to `false`.
-- `Autotuner.sample_ratio=`: (optional) Sets the portion of instances where autotuner is enabled. Pass a value between 0 (enabled on no intances) and 1.0 (enabled on all instances). Note that this does not sample reqeusts, but rather samples the portion of instances that have autotuner enabled (it will be enabled for all requests on those instances). Do not configure `Autotuner.enabled=` when you use this option.
+- `Autotuner.sample_ratio=`: (optional) Sets the portion of instances where autotuner is enabled. Pass a value between 0 (enabled on no instances) and 1.0 (enabled on all instances). Note that this does not sample requests, but rather samples the portion of instances that have autotuner enabled (it will be enabled for all requests on those instances). Do not configure `Autotuner.enabled=` when you use this option.
 - `Autotuner.reporter=`: (required) Callback called when a heuristic is ready to give a suggestion. The callback will be called with one argument which will be an instance of `Autotuner::Report::Base`. Call `#to_s` on this object to get a string containing instructions and recommendations. You must set this when autotuner is enabled.
 - `Autotuner.debug_reporter=`: (optional) Callback to periodically emit debug messages of internal state of heuristics. The callback will be called with one argument which will be a hash with the heuristic name as the key and the debug message as the value. Regular users do not need to configure this as this is only useful for debugging purposes.
 - `Autotuner.metrics_reporter=`: (optional) Callback to emit useful metrics about your service. The callback will be called with a hash containing the metric names (string) as the key and integer values.
 
+## Emitted Metrics
+
+The following metrics are passed to the `metrics_reporter` callback after each request.
+
+| Name                  | Description |
+| --------------------- | ----------- |
+| `diff.time`           | Time spent doing garbage collection during the request. Produced by [GC::stat](https://docs.ruby-lang.org/en/master/GC.html#method-c-stat) |
+| `diff.minor_gc_count` | Number of minor garbage collections that occurred during the request. Produced by [GC::stat](https://docs.ruby-lang.org/en/master/GC.html#method-c-stat) |
+| `diff.major_gc_count` | Number of major garbage collections that occurred during the request. Produced by [GC::stat](https://docs.ruby-lang.org/en/master/GC.html#method-c-stat) |
+| `heap_pages`          | Number of heap pages in use after the request. Produced by [GC::stat](https://docs.ruby-lang.org/en/master/GC.html#method-c-stat) |
+| `request_time`        | Total duration of the request. |
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/autotuner.

data/lib/autotuner/heuristic/base.rb

@@ -5,15 +5,13 @@ module Autotuner
     class Base
       class << self
         def enabled?
-          supported? && !@disabled
+          !@disabled
         end
 
         def disable!
           @disabled = true
         end
 
-        private
-
         def supported?
           raise NotImplementedError
         end

data/lib/autotuner/heuristic/gc_compact.rb

@@ -4,8 +4,6 @@ module Autotuner
   module Heuristic
     class GCCompact < Base
       class << self
-        private
-
         def supported?
           true
         end
@@ -41,12 +39,24 @@ module Autotuner
             3.times { GC.start }
             GC.compact
 
-          For example, in Puma, add the following code into config/puma.rb:
+          For example, with Puma, which runs its before fork hook once on boot (before the initial fork), add the following code into config/puma.rb:
 
             before_fork do
               3.times { GC.start }
               GC.compact
             end
+
+          With Unicorn, which runs its before fork hook before each fork, add the following code into config/unicorn.rb:
+
+            compacted = false
+            before_fork do
+              # avoid invalidating heap pages shared with previously forked children
+              unless compacted
+                3.times { GC.start }
+                GC.compact
+                compacted = true
+              end
+            end
         MSG
       end
 

data/lib/autotuner/heuristic/heap_size_warmup.rb

@@ -4,8 +4,6 @@ module Autotuner
   module Heuristic
     class HeapSizeWarmup < Base
       class << self
-        private
-
         def supported?
           # Ruby 3.2 uses multiple heaps but does not support the
           # RUBY_GC_HEAP_%d_INIT_SLOTS environment variables, so we cannot
@@ -28,7 +26,7 @@ module Autotuner
       HEAP_SIZE_CONFIGURATION_DELTA = 1_000
 
       REPORT_ASSIST_MESSAGE = <<~MSG
-        The following suggestions adjusts the size of heap at boot time, which can improve bootup speed and reduce the time taken for the app to reach peak performance.
+        The following suggestions adjust the size of the heap at boot time, which can improve bootup speed and reduce the time taken for the app to reach peak performance.
       MSG
 
       def initialize(_system_context)

data/lib/autotuner/heuristic/malloc.rb

@@ -4,8 +4,6 @@ module Autotuner
   module Heuristic
     class Malloc < Base
       class << self
-        private
-
         def supported?
           true
         end
@@ -68,9 +66,9 @@ module Autotuner
 
         Report::MultipleEnvironmentVariables.new(
           <<~MSG,
-            The following suggestions reduces the number of minor garbage collection cycles, specifically a cycle called "malloc". Your app runs malloc cycles in approximately #{format("%.2f", malloc_gc_ratio * 100)}% of all minor garbage collection cycles.
+            The following suggestions reduce the number of minor garbage collection cycles, specifically a cycle called "malloc". Your app runs malloc cycles in approximately #{format("%.2f", malloc_gc_ratio * 100)}% of all minor garbage collection cycles.
 
-            Reducing minor garbage collection cycles can help reduce response times. The following tuning values aims to reduce malloc garbage collection cycles by setting it to a higher value. This may cause a slight increase in memory usage. You should monitor memory usage carefully to ensure your app is not running out of memory.
+            Reducing minor garbage collection cycles can help reduce response times. The following tuning values aim to reduce malloc garbage collection cycles by setting it to a higher value. This may cause a slight increase in memory usage. You should monitor memory usage carefully to ensure your app is not running out of memory.
           MSG
           [LIMIT_ENV, LIMIT_MAX_ENV],
           # Suggest to double the limit and max

data/lib/autotuner/heuristic/oldmalloc.rb

@@ -4,8 +4,6 @@ module Autotuner
   module Heuristic
     class Oldmalloc < Base
       class << self
-        private
-
         def supported?
           true
         end
@@ -67,9 +65,9 @@ module Autotuner
 
         Report::MultipleEnvironmentVariables.new(
           <<~MSG,
-            The following suggestions reduces the number of major garbage collection cycles, specifically a cycle called "oldmalloc". Your app runs oldmalloc cycles in approximately #{format("%.2f", oldmalloc_gc_ratio * 100)}% of all major garbage collection cycles.
+            The following suggestions reduce the number of major garbage collection cycles, specifically a cycle called "oldmalloc". Your app runs oldmalloc cycles in approximately #{format("%.2f", oldmalloc_gc_ratio * 100)}% of all major garbage collection cycles.
 
-            Reducing major garbage collection cycles can help reduce response times, especially for the extremes (e.g. p95 or p99 response times). The following tuning values aims to disable oldmalloc garbage collection cycles by setting it to an extremely high value. This may cause a slight increase in memory usage. You should monitor memory usage carefully to ensure your app is not running out of memory.
+            Reducing major garbage collection cycles can help reduce response times, especially for the extremes (e.g. p95 or p99 response times). The following tuning values aim to disable oldmalloc garbage collection cycles by setting it to an extremely high value. This may cause a slight increase in memory usage. You should monitor memory usage carefully to ensure your app is not running out of memory.
           MSG
           [LIMIT_ENV, LIMIT_MAX_ENV],
           [LIMIT_ENV_SUGGESTED_VALUE, LIMIT_MAX_SUGGESTED_VALUE],

data/lib/autotuner/heuristic/remembered_wb_unprotected_objects.rb

@@ -4,8 +4,6 @@ module Autotuner
   module Heuristic
     class RememberedWBUnprotectedObjects < Base
       class << self
-        private
-
         def supported?
           # Ruby 3.3.0 and later have support RUBY_GC_HEAP_REMEMBERED_WB_UNPROTECTED_OBJECTS_LIMIT_RATIO
           RUBY_VERSION >= "3.3.0"
@@ -65,9 +63,9 @@ module Autotuner
 
         Report::SingleEnvironmentVariable.new(
           <<~MSG,
-            The following suggestions reduces the number of major garbage collection cycles, specifically a cycle called "remembered write barrier unprotected" (also know as "shady" due to historical reasons). Your app runs remembered write barrier unprotected cycles in approximately #{format("%.2f", wb_unprotected_gc_ratio * 100)}% of all major garbage collection cycles.
+            The following suggestions reduce the number of major garbage collection cycles, specifically a cycle called "remembered write barrier unprotected" (also know as "shady" due to historical reasons). Your app runs remembered write barrier unprotected cycles in approximately #{format("%.2f", wb_unprotected_gc_ratio * 100)}% of all major garbage collection cycles.
 
-            Reducing major garbage collection cycles can help reduce response times, especially for the extremes (e.g. p95 or p99 response times). The following tuning values aims to disable oldmalloc garbage collection cycles by setting it to an extremely high value. This may cause a slight increase in memory usage. You should monitor memory usage carefully to ensure your app is not running out of memory.
+            Reducing major garbage collection cycles can help reduce response times, especially for the extremes (e.g. p95 or p99 response times). The following tuning values aim to disable oldmalloc garbage collection cycles by setting it to an extremely high value. This may cause a slight increase in memory usage. You should monitor memory usage carefully to ensure your app is not running out of memory.
           MSG
           LIMIT_RATIO_ENV,
           suggested_limit_ratio,

data/lib/autotuner/heuristics.rb

@@ -3,10 +3,10 @@
 module Autotuner
   module Heuristics
     HEURISTICS = Heuristic::Base.subclasses.freeze
-    ENABLED_HEURISTICS = HEURISTICS.dup.keep_if(&:enabled?).freeze
+    SUPPORTED_HEURISTICS = HEURISTICS.dup.keep_if(&:supported?).freeze
 
-    def enabled_heuristics
-      ENABLED_HEURISTICS
+    def supported_heuristics
+      SUPPORTED_HEURISTICS
     end
   end
 end

data/lib/autotuner/request_collector.rb

@@ -5,8 +5,6 @@ module Autotuner
     HEURISTICS_POLLING_FREQUENCY = 100
     DEBUG_EMIT_FREQUENCY = 1000
 
-    attr_reader :heuristics
-
     def initialize
       @request_count = 0
 
@@ -14,7 +12,7 @@ module Autotuner
 
       @system_context = SystemContext.new
 
-      @heuristics = Autotuner.enabled_heuristics.map { |h| h.new(@system_context) }
+      @heuristics = Autotuner.supported_heuristics.map { |h| h.new(@system_context) }
     end
 
     def request
@@ -27,6 +25,16 @@ module Autotuner
 
     private
 
+    def enabled_heuristics
+      Enumerator.new do |y|
+        @heuristics.each do |heuristic|
+          next unless heuristic.class.enabled?
+
+          y << heuristic
+        end
+      end
+    end
+
     def before_request
       @request_context.before_request
 
@@ -38,7 +46,7 @@ module Autotuner
 
       @system_context.update(@request_context)
 
-      heuristics.each do |heuristic|
+      enabled_heuristics.each do |heuristic|
         heuristic.call(@request_context)
       end
 
@@ -48,7 +56,7 @@ module Autotuner
     end
 
     def emit_heuristic_reports
-      heuristics.each do |heuristic|
+      enabled_heuristics.each do |heuristic|
         report = heuristic.tuning_report
 
         next unless report
@@ -68,7 +76,7 @@ module Autotuner
         system_context: @system_context.debug_state,
       }
 
-      heuristics.each do |h|
+      enabled_heuristics.each do |h|
         debug_states[h.name] = h.debug_state
       end
 

data/lib/autotuner/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Autotuner
-  VERSION = "1.0.0"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: autotuner
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Peter Zhu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-28 00:00:00.000000000 Z
+date: 2024-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mocha
@@ -60,7 +60,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".ruby-version"
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -98,14 +100,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Get suggestions to tune Ruby's garbage collector