add enabled configuration option and force parameter for per-request profiling

Author: joshuay03

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## [Unreleased]
 
 - Don't clean up stale storage data in railtie
+- Add enabled configuration option and force parameter for per-request profiling
 
 ## [0.5.0] - 2025-09-21
 

README.md

@@ -41,9 +41,15 @@ mount Dial::Engine, at: "/"
 # config/initializers/dial.rb
 
 Dial.configure do |config|
-  config.sampling_percentage = 50
-  config.storage = Dial::Storage::RedisAdapter
-  config.storage_options = { client: Redis.new(url: ENV["REDIS_URL"]), ttl: 86400 }
+  config.enabled = !Rails.env.production? # disable by default in production, use force_param to enable per request
+  config.force_param = "profile" # override param name to force profiling
+  if Rails.env.staging?
+    config.sampling_percentage = 50 # override sampling percentage in staging for A/B testing profiler impact
+  end
+  unless Rails.env.development?
+    config.storage = Dial::Storage::RedisAdapter # use Redis storage in non-development environments
+    config.storage_options = { client: Redis.new(url: ENV["REDIS_URL"]), ttl: 86400 }
+  end
   config.vernier_interval = 100
   config.vernier_allocation_interval = 10_000
   config.prosopite_ignore_queries += [/pg_sleep/i]
@@ -54,9 +60,11 @@ end
 
 Option | Description | Default
 :- | :- | :-
+`enabled` | Whether profiling is enabled. | `true`
+`force_param` | Request parameter name to force profiling even when disabled. Always profiles (bypasses sampling). | `"dial_force"`
 `sampling_percentage` | Percentage of requests to profile. | `100` in development, `1` in production
-`storage` | Storage adapter class for profile data | `Dial::Storage::FileAdapter`
-`storage_options` | Options hash passed to storage adapter | `{ ttl: 3600 }`
+`storage` | Storage adapter class for profile data. | `Dial::Storage::FileAdapter`
+`storage_options` | Options hash passed to storage adapter. | `{ ttl: 3600 }`
 `content_security_policy_nonce` | Sets the content security policy nonce to use when inserting Dial's script. Can be a string, or a Proc which receives `env` and response `headers` as arguments and returns the nonce string. | Rails generated nonce or `nil`
 `vernier_interval` | Sets the `interval` option for vernier. | `200`
 `vernier_allocation_interval` | Sets the `allocation_interval` option for vernier. | `2_000`

lib/dial/configuration.rb

@@ -12,8 +12,10 @@ def self._configuration
   class Configuration
     def initialize
       @options = {
-        sampling_percentage: default_sampling_percentage,
-        storage: default_storage,
+        enabled: true,
+        force_param: FORCE_PARAM,
+        sampling_percentage: ::Rails.env.development? ? SAMPLING_PERCENTAGE_DEV : SAMPLING_PERCENTAGE_PROD,
+        storage: Storage::FileAdapter,
         storage_options: { ttl: STORAGE_TTL },
         content_security_policy_nonce: -> env, _headers { env[NONCE] || EMPTY_NONCE },
         vernier_interval: VERNIER_INTERVAL,
@@ -37,15 +39,5 @@ def freeze
 
       super
     end
-
-    private
-
-    def default_sampling_percentage
-      ::Rails.env.development? ? SAMPLING_PERCENTAGE_DEV : SAMPLING_PERCENTAGE_PROD
-    end
-
-    def default_storage
-      Storage::FileAdapter
-    end
   end
 end

lib/dial/constants.rb

@@ -16,6 +16,7 @@ module Dial
   NONCE = ::ActionDispatch::ContentSecurityPolicy::Request::NONCE
   REQUEST_TIMING = "dial_request_timing"
 
+  FORCE_PARAM = "dial_force"
   SAMPLING_PERCENTAGE_DEV = 100
   SAMPLING_PERCENTAGE_PROD = 1
   STORAGE_TTL = 60 * 60

lib/dial/middleware.rb

@@ -22,7 +22,8 @@ def call env
         return @app.call env
       end
 
-      unless should_profile?
+      request = ::Rack::Request.new env
+      unless should_profile? request
         return @app.call env
       end
 
@@ -125,8 +126,12 @@ def process_query_log_line line, entry, section, count
       end
     end
 
-    def should_profile?
-      rand(100) < Dial._configuration.sampling_percentage
+    def should_profile? request
+      force_param = Dial._configuration.force_param
+      return true if request.params[force_param]
+
+      Dial._configuration.enabled &&
+        rand(100) < Dial._configuration.sampling_percentage
     end
   end
 

test/dial/test_configuration.rb

@@ -12,6 +12,8 @@ def test_configure_yields_a_new_configuration
 
     def test_configuration_has_default_values
       Dial.configure do |config|
+        assert_equal true, config.enabled
+        assert_equal FORCE_PARAM, config.force_param
         assert_equal 100, config.sampling_percentage
         assert_instance_of Proc, config.content_security_policy_nonce
         assert_equal VERNIER_INTERVAL, config.vernier_interval
@@ -24,17 +26,21 @@ def test_configuration_has_default_values
 
     def test_configuration_can_be_changed
       Dial.configure do |config|
+        config.enabled = false
+        config.force_param = "profile"
         config.sampling_percentage = 25
         config.content_security_policy_nonce = lambda { |_env, headers| headers["TEST_NONCE"] }
         config.vernier_interval = 50
         config.vernier_allocation_interval = 100
         config.prosopite_ignore_queries = [/only_ignore_me/]
 
+        assert_equal false, config.enabled
+        assert_equal "profile", config.force_param
         assert_equal 25, config.sampling_percentage
+        assert_equal "test_nonce", config.content_security_policy_nonce.call({}, { "TEST_NONCE" => "test_nonce" })
         assert_equal 50, config.vernier_interval
         assert_equal 100, config.vernier_allocation_interval
         assert_equal [/only_ignore_me/], config.prosopite_ignore_queries
-        assert_equal "test_nonce", config.content_security_policy_nonce.call({}, { "TEST_NONCE" => "test_nonce" })
       end
     end
   end
@@ -49,15 +55,21 @@ def teardown
     def test_configuration_can_be_changed
       config_initializer <<~RUBY
         Dial.configure do |config|
+          config.enabled = false
+          config.force_param = "profile"
           config.sampling_percentage = 25
+          config.content_security_policy_nonce = lambda { |_env, headers| headers["TEST_NONCE"] }
           config.vernier_interval = 50
           config.vernier_allocation_interval = 100
           config.prosopite_ignore_queries = [/only_ignore_me/]
         end
       RUBY
       app(true).initialize!
 
+      assert_equal false, Dial._configuration.enabled
+      assert_equal "profile", Dial._configuration.force_param
       assert_equal 25, Dial._configuration.sampling_percentage
+      assert_equal "test_nonce", Dial._configuration.content_security_policy_nonce.call({}, { "TEST_NONCE" => "test_nonce" })
       assert_equal 50, Dial._configuration.vernier_interval
       assert_equal 100, Dial._configuration.vernier_allocation_interval
       assert_equal [/only_ignore_me/], Dial._configuration.prosopite_ignore_queries

test/dial/test_middleware.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../test_helper"
+
+module Dial
+  class TestMiddleware < Dial::Test
+    def setup
+      super
+      @app = lambda { |env| [200, { "Content-Type" => "text/html" }, ["<html><body>Test</body></html>"]] }
+      @middleware = Middleware.new @app
+      @base_env = {
+        "HTTP_ACCEPT" => "text/html",
+        "REQUEST_METHOD" => "GET",
+        "PATH_INFO" => "/test",
+        "HTTP_HOST" => "example.com"
+      }
+      @base_request = ::Rack::Request.new @base_env
+    end
+
+    def test_should_profile_when_enabled
+      assert @middleware.send :should_profile?, @base_request
+    end
+
+    def test_should_not_profile_when_not_within_sampling
+      with_config sampling_percentage: 0 do
+        refute @middleware.send :should_profile?, @base_request
+      end
+    end
+
+    def test_should_not_profile_when_disabled
+      with_config enabled: false do
+        refute @middleware.send :should_profile?, @base_request
+      end
+    end
+
+    def test_should_profile_when_disabled_and_forced
+      with_config enabled: false, force_param: "profile" do
+        env = @base_env.merge "QUERY_STRING" => "profile=1"
+        request = ::Rack::Request.new env
+
+        assert @middleware.send :should_profile?, request
+      end
+    end
+
+    def test_should_profile_when_disabled_and_forced_and_not_within_sampling
+      with_config enabled: false, force_param: "profile", sampling_percentage: 0 do
+        env = @base_env.merge "QUERY_STRING" => "profile=1"
+        request = ::Rack::Request.new env
+
+        assert @middleware.send :should_profile?, request
+      end
+    end
+
+    private
+
+    def with_config options = {}
+      original_config = Dial._configuration.instance_variable_get :@options
+      new_config = original_config.merge options
+
+      Dial._configuration.instance_variable_set :@options, new_config
+      yield
+    ensure
+      Dial._configuration.instance_variable_set :@options, original_config
+    end
+  end
+end