autotuner 0.1.0 → 1.0.0

data/lib/autotuner/heuristic/remembered_wb_unprotected_objects.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+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"
+        end
+      end
+
+      WB_UNPROTECTED_GC_RATIO_THRESHOLD = 0.1
+      MIN_WB_UNPROTECTED_GC = 10
+
+      # From the GC_HEAP_REMEMBERED_WB_UNPROTECTED_OBJECTS_LIMIT_RATIO macro
+      # https://github.com/ruby/ruby/blob/df4c77608e76068deed58b2781674b0eb247c325/gc.c#L295
+      DEFAULT_LIMIT_RATIO = 0.01
+
+      LIMIT_RATIO_ENV = "RUBY_GC_HEAP_REMEMBERED_WB_UNPROTECTED_OBJECTS_LIMIT_RATIO"
+
+      attr_reader :major_gc_count
+      attr_reader :remembered_wb_unprotected_gc_count
+
+      def initialize(_system_context)
+        super
+
+        @major_gc_count = 0
+        @remembered_wb_unprotected_gc_count = 0
+
+        @given_suggestion = false
+      end
+
+      def name
+        "WBUnprotectedObjects"
+      end
+
+      def call(request_context)
+        # major_by is only useful if we ran at least one major GC during the request
+        if request_context.after_gc_context.stat[:major_gc_count] ==
+            request_context.before_gc_context.stat[:major_gc_count]
+          return
+        end
+
+        # Technically, we could run more than one major GC in the request, but
+        # since we don't have information about the other major GC, we'll treat
+        # it as if there was only one major GC.
+        @major_gc_count += 1
+        @remembered_wb_unprotected_gc_count += 1 if request_context.after_gc_context.latest_gc_info[:major_by] == :shady
+      end
+
+      def tuning_report
+        # Don't give suggestions twice
+        return if @given_suggestion
+        # Don't report if there's very few data points
+        return if @remembered_wb_unprotected_gc_count < MIN_WB_UNPROTECTED_GC
+
+        wb_unprotected_gc_ratio = @remembered_wb_unprotected_gc_count.to_f / @major_gc_count
+        # Don't report if there's very few WB unprotected GC
+        return if wb_unprotected_gc_ratio <= WB_UNPROTECTED_GC_RATIO_THRESHOLD
+
+        @given_suggestion = true
+
+        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.
+
+            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.
+          MSG
+          LIMIT_RATIO_ENV,
+          suggested_limit_ratio,
+          configured_limit_ratio,
+        )
+      end
+
+      def debug_state
+        {
+          given_suggestion: @given_suggestion,
+          major_gc_count: @major_gc_count,
+          remembered_wb_unprotected_gc_count: @remembered_wb_unprotected_gc_count,
+        }
+      end
+
+      private
+
+      def configured_limit_ratio
+        ENV[LIMIT_RATIO_ENV]&.to_f
+      end
+
+      def suggested_limit_ratio
+        if !configured_limit_ratio
+          DEFAULT_LIMIT_RATIO * 2
+        elsif configured_limit_ratio < DEFAULT_LIMIT_RATIO
+          DEFAULT_LIMIT_RATIO
+        else
+          configured_limit_ratio * 2
+        end
+      end
+    end
+  end
+end

data/lib/autotuner/heuristics.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Autotuner
+  module Heuristics
+    HEURISTICS = Heuristic::Base.subclasses.freeze
+    ENABLED_HEURISTICS = HEURISTICS.dup.keep_if(&:enabled?).freeze
+
+    def enabled_heuristics
+      ENABLED_HEURISTICS
+    end
+  end
+end

data/lib/{gc_tuner → autotuner}/rack_plugin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module GCTuner
+module Autotuner
   class RackPlugin
     def initialize(app)
       @app = app
@@ -8,7 +8,7 @@ module GCTuner
     end
 
     def call(env)
-      if GCTuner.enabled?
+      if Autotuner.enabled?
         @request_collector.request do
           @app.call(env)
         end

data/lib/autotuner/report/base.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Autotuner
+  module Report
+    class Base
+      DISCLAIMER_MESSAGE = <<~MSG
+        It is always recommended to experiment with these suggestions as some suggestions may not always yield positive performance improvements. The recommended method is to perform A/B testing where a portion of traffic does not have the these suggested values and a portion of traffic with these suggested values.
+      MSG
+
+      attr_reader :assist_message
+
+      def initialize(assist_message)
+        @assist_message = assist_message
+      end
+
+      def to_s
+        msg = +assist_message
+        msg << "\n"
+
+        m = message
+        if m
+          msg << m
+          msg << "\n"
+        end
+
+        msg << DISCLAIMER_MESSAGE
+        msg.freeze
+      end
+
+      private
+
+      def message
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/autotuner/report/multiple_environment_variables.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Autotuner
+  module Report
+    class MultipleEnvironmentVariables < Base
+      attr_reader :env_name
+      attr_reader :suggested_value
+      attr_reader :configured_value
+
+      def initialize(assist_message, env_name, suggested_value, configured_value)
+        super(assist_message)
+        @env_name = env_name
+        @suggested_value = suggested_value
+        @configured_value = configured_value
+      end
+
+      private
+
+      def message
+        msg = +"Suggested tuning values:\n"
+        env_name.each_with_index do |env, i|
+          msg << suggested_tuning_str(env, suggested_value[i], configured_value[i])
+        end
+        msg
+      end
+
+      def suggested_tuning_str(env, suggested, configured)
+        str = +"  #{env}=#{suggested}"
+        str << " (configured value: #{configured})" if configured
+        str << "\n"
+        str
+      end
+    end
+  end
+end

data/lib/autotuner/report/single_environment_variable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Autotuner
+  module Report
+    class SingleEnvironmentVariable < Base
+      attr_reader :env_name
+      attr_reader :suggested_value
+      attr_reader :configured_value
+
+      def initialize(assist_message, env_name, suggested_value, configured_value)
+        super(assist_message)
+
+        @env_name = env_name
+        @suggested_value = suggested_value
+        @configured_value = configured_value
+      end
+
+      private
+
+      def message
+        msg = +"Suggested tuning value:\n"
+        msg << "  #{env_name}=#{suggested_value}"
+        msg << " (configured value: #{configured_value})" if configured_value
+        msg << "\n"
+        msg
+      end
+    end
+  end
+end

data/lib/autotuner/report/string.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Autotuner
+  module Report
+    class String < Base
+      private
+
+      def message
+        nil
+      end
+    end
+  end
+end

data/lib/autotuner/request_collector.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Autotuner
+  class RequestCollector
+    HEURISTICS_POLLING_FREQUENCY = 100
+    DEBUG_EMIT_FREQUENCY = 1000
+
+    attr_reader :heuristics
+
+    def initialize
+      @request_count = 0
+
+      @request_context = RequestContext.new
+
+      @system_context = SystemContext.new
+
+      @heuristics = Autotuner.enabled_heuristics.map { |h| h.new(@system_context) }
+    end
+
+    def request
+      before_request
+
+      yield
+    ensure
+      after_request
+    end
+
+    private
+
+    def before_request
+      @request_context.before_request
+
+      @request_count += 1
+    end
+
+    def after_request
+      @request_context.after_request
+
+      @system_context.update(@request_context)
+
+      heuristics.each do |heuristic|
+        heuristic.call(@request_context)
+      end
+
+      emit_heuristic_reports if @request_count % HEURISTICS_POLLING_FREQUENCY == 0
+      emit_debugging_states if @request_count % DEBUG_EMIT_FREQUENCY == 0
+      emit_metrics
+    end
+
+    def emit_heuristic_reports
+      heuristics.each do |heuristic|
+        report = heuristic.tuning_report
+
+        next unless report
+
+        if Autotuner.reporter
+          Autotuner.reporter.call(report)
+        else
+          warn("Autotuner has been enabled but Autotuner.reporter has not been configured")
+        end
+      end
+    end
+
+    def emit_debugging_states
+      return unless Autotuner.debug_reporter
+
+      debug_states = {
+        system_context: @system_context.debug_state,
+      }
+
+      heuristics.each do |h|
+        debug_states[h.name] = h.debug_state
+      end
+
+      Autotuner.debug_reporter.call(debug_states)
+    end
+
+    def emit_metrics
+      return unless Autotuner.metrics_reporter
+
+      metrics = {
+        # Diff metrics
+        "diff.time" => gc_stat_diff(:time),
+        "diff.minor_gc_count" => gc_stat_diff(:minor_gc_count),
+        "diff.major_gc_count" => gc_stat_diff(:major_gc_count),
+        "request_time" => @request_context.request_time,
+
+        # Metrics
+        "heap_pages" => @request_context.after_gc_context.stat[:heap_eden_pages],
+      }
+
+      Autotuner.metrics_reporter.call(metrics)
+    end
+
+    def gc_stat_diff(stat)
+      @request_context.after_gc_context.stat[stat] - @request_context.before_gc_context.stat[stat]
+    end
+  end
+end

data/lib/{gc_tuner/request_collector.rb → autotuner/request_context.rb}

@@ -1,36 +1,27 @@
 # frozen_string_literal: true
 
-module GCTuner
-  class RequestCollector
+module Autotuner
+  class RequestContext
+    attr_reader :before_gc_context
+    attr_reader :after_gc_context
+    attr_reader :request_time
+
     def initialize
       @before_gc_context = GCContext.new
       @after_gc_context = GCContext.new
+      @request_time = 0.0
 
       @start_time_ms = 0.0
     end
 
-    def request
-      before_request
-
-      yield
-    ensure
-      after_request
-    end
-
-    private
-
     def before_request
       @before_gc_context.update
       @start_time_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
     end
 
     def after_request
-      request_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - @start_time_ms
+      @request_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - @start_time_ms
       @after_gc_context.update
-
-      GCTuner.heuristics.each do |heuristic|
-        heuristic.call(request_time, @before_gc_context, @after_gc_context)
-      end
     end
   end
 end

data/lib/autotuner/system_context.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Autotuner
+  class SystemContext
+    attr_reader :request_time_data
+
+    def initialize
+      @request_time_data = DataStructure::DataPoints.new(Configuration::DATA_POINTS_COUNT)
+    end
+
+    def update(request_context)
+      @request_time_data.insert(request_context.request_time)
+    end
+
+    def debug_state
+      {
+        request_time_data: @request_time_data.debug_state,
+      }
+    end
+  end
+end

data/lib/autotuner/version.rb

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

data/lib/autotuner.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "autotuner/data_structure/data_points"
+
+require_relative "autotuner/heuristic/base"
+require_relative "autotuner/heuristic/gc_compact"
+require_relative "autotuner/heuristic/heap_size_warmup"
+require_relative "autotuner/heuristic/malloc"
+require_relative "autotuner/heuristic/oldmalloc"
+require_relative "autotuner/heuristic/remembered_wb_unprotected_objects"
+
+require_relative "autotuner/report/base"
+require_relative "autotuner/report/multiple_environment_variables"
+require_relative "autotuner/report/single_environment_variable"
+require_relative "autotuner/report/string"
+
+require_relative "autotuner/configuration"
+require_relative "autotuner/gc_context"
+require_relative "autotuner/heuristics"
+require_relative "autotuner/rack_plugin"
+require_relative "autotuner/request_collector"
+require_relative "autotuner/request_context"
+require_relative "autotuner/system_context"
+require_relative "autotuner/version"
+
+module Autotuner
+  extend Configuration
+  extend Heuristics
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: autotuner
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Peter Zhu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-06-13 00:00:00.000000000 Z
+date: 2023-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mocha
@@ -64,22 +64,32 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- lib/gc_tuner.rb
-- lib/gc_tuner/configuration.rb
-- lib/gc_tuner/data_structure/data_points.rb
-- lib/gc_tuner/gc_context.rb
-- lib/gc_tuner/heuristic/base.rb
-- lib/gc_tuner/heuristic/size_pool_warmup.rb
-- lib/gc_tuner/heuristics.rb
-- lib/gc_tuner/rack_plugin.rb
-- lib/gc_tuner/request_collector.rb
-- lib/gc_tuner/version.rb
-homepage: https://github.com/Shopify/gc_tuner
+- lib/autotuner.rb
+- lib/autotuner/configuration.rb
+- lib/autotuner/data_structure/data_points.rb
+- lib/autotuner/gc_context.rb
+- lib/autotuner/heuristic/base.rb
+- lib/autotuner/heuristic/gc_compact.rb
+- lib/autotuner/heuristic/heap_size_warmup.rb
+- lib/autotuner/heuristic/malloc.rb
+- lib/autotuner/heuristic/oldmalloc.rb
+- lib/autotuner/heuristic/remembered_wb_unprotected_objects.rb
+- lib/autotuner/heuristics.rb
+- lib/autotuner/rack_plugin.rb
+- lib/autotuner/report/base.rb
+- lib/autotuner/report/multiple_environment_variables.rb
+- lib/autotuner/report/single_environment_variable.rb
+- lib/autotuner/report/string.rb
+- lib/autotuner/request_collector.rb
+- lib/autotuner/request_context.rb
+- lib/autotuner/system_context.rb
+- lib/autotuner/version.rb
+homepage: https://github.com/Shopify/autotuner
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/Shopify/gc_tuner
-  source_code_uri: https://github.com/Shopify/gc_tuner
+  homepage_uri: https://github.com/Shopify/autotuner
+  source_code_uri: https://github.com/Shopify/autotuner
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/gc_tuner/configuration.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module GCTuner
-  module Configuration
-    attr_reader :sample_ratio
-    attr_writer :enabled
-
-    def enabled?
-      @enabled
-    end
-
-    def sample_ratio=(ratio)
-      raise ArgumentError, "ratio must be between 0 and 1.0" unless (0..1.0).include?(ratio)
-
-      @sample_ratio = ratio
-
-      self.enabled = rand < ratio
-    end
-  end
-end

data/lib/gc_tuner/gc_context.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module GCTuner
-  class GCContext
-    attr_reader :stat, :stat_heap
-
-    def initialize
-      @stat = GC.stat
-      @stat_heap = GC.stat_heap
-    end
-
-    def update
-      GC.stat(@stat)
-      GC.stat_heap(nil, @stat_heap)
-    end
-  end
-end

data/lib/gc_tuner/heuristic/size_pool_warmup.rb

@@ -1,131 +0,0 @@
-# frozen_string_literal: true
-
-module GCTuner
-  module Heuristic
-    class SizePoolWarmup < Base
-      DATA_POINTS_COUNT = 1_000
-      SIZE_POOL_CONFIGURATION_DELTA_RATIO = 0.01
-      SIZE_POOL_CONFIGURATION_DELTA = 1
-
-      class << self
-        private
-
-        def supported?
-          # Ruby 3.3.0 and later have support RUBY_GC_HEAP_INIT_SIZE_%d_SLOTS
-          # RUBY_VERSION >= "3.3.0"
-          # TODO: use the check above
-          true
-        end
-      end
-
-      def initialize
-        super
-
-        @request_time_data = DataStructure::DataPoints.new(DATA_POINTS_COUNT)
-
-        @size_pool_count = GC::INTERNAL_CONSTANTS[:SIZE_POOL_COUNT]
-        @size_pools_data = Array.new(@size_pool_count)
-        @size_pools_tuning_configuration = Array.new(@size_pool_count)
-        @size_pool_count.times do |i|
-          @size_pools_data[i] = DataStructure::DataPoints.new(DATA_POINTS_COUNT)
-          @size_pools_tuning_configuration[i] = ENV[env_name_for_size_pool(i)].to_i
-        end
-
-        @plateaued = false
-      end
-
-      def call(request_time, _before_gc_context, after_gc_context)
-        # We only want to collect data at boot until the request time plateaus
-        return if @plateaued
-
-        insert_data(request_time, after_gc_context)
-
-        return unless @request_time_data.plateaued?
-
-        @plateaued = true
-      end
-
-      def tuning_message
-        msg = nil
-
-        if @plateaued
-          size_pool_messages = @size_pool_count.times.map do |i|
-            tuning_message_for_size_pool(i)
-          end.compact
-
-          unless size_pool_messages.empty?
-            msg = <<~MSG
-              Here are the recommended tuning values for size pools and the confidence scores.
-              Confidence scores are between 0 and 1.0 and represent the correlation between
-              the tuning value and the response time.
-
-            MSG
-
-            msg += size_pool_messages.join
-          end
-        else
-          msg = <<~MSG.chomp
-            There is not enough data and/or response times have not plateaued.
-          MSG
-        end
-
-        msg
-      end
-
-      def debug_message
-        msg = <<~MSG
-          plateaued: #{@plateaued}
-          request_time_data: #{@request_time_data}
-        MSG
-
-        @size_pools_data.each_with_index do |data, i|
-          msg += "size_pools_data[#{i}]: #{data}\n"
-        end
-
-        if @plateaued
-          msg += @size_pool_count.times.map do |i|
-            tuning_message_for_size_pool(i, debug: true)
-          end.join
-        end
-
-        msg
-      end
-
-      private
-
-      def insert_data(request_time, after_gc_context)
-        @request_time_data.insert(request_time)
-
-        @size_pools_data.each_with_index do |data, i|
-          data.insert(after_gc_context.stat_heap[i][:heap_eden_pages])
-        end
-      end
-
-      def env_name_for_size_pool(size_pool)
-        slot_size = GC::INTERNAL_CONSTANTS[:BASE_SLOT_SIZE] * (2**size_pool)
-
-        "RUBY_GC_HEAP_INIT_SIZE_#{slot_size}_SLOTS"
-      end
-
-      def tuning_message_for_size_pool(size_pool, debug: false)
-        configured_value = @size_pools_tuning_configuration[size_pool]
-
-        data = @size_pools_data[size_pool]
-        suggested_value = data.samples[data.length - 1].to_i
-
-        diff = (configured_value - suggested_value).abs
-        if debug ||
-            (diff > configured_value * SIZE_POOL_CONFIGURATION_DELTA_RATIO && diff > SIZE_POOL_CONFIGURATION_DELTA)
-          confidence = @request_time_data.correlation(data).abs
-
-          msg = ""
-          msg += "#{env_name_for_size_pool(size_pool)}=#{suggested_value} (confidence: #{format("%.2f", confidence)}"
-          msg += ", tuned value: #{configured_value}" if configured_value > 0
-          msg += ")\n"
-
-          msg
-        end
-      end
-    end
-  end
-end