rails_memory_profiler 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ecc5cf3944827bacd93b4ba2609cf46516c1a2ecf54ff922e1b36d36e7e1592
-  data.tar.gz: 50de3643fab494e8d03a494d4c776914c234469844b095deb0964efbf94036ce
+  metadata.gz: 0cfc3104434c10aa68686413abf2c879661158fde43cbe61c53cf31f45154b6f
+  data.tar.gz: 114b4471fca8c8a32c2d0ea00debec64f2e338d3b92268bff205ab1db871e73a
 SHA512:
-  metadata.gz: '091da3ac58edfd24e7fb0c8090e782a9af30d08dd2f5d59054b9f8108704c99f2c7ac238def2004730c22a77442ece51375ed221694666b828b76cb589e8dd0c'
-  data.tar.gz: 8bd3e45989fe1cac7bb15b02304d8e846977fa643652d949f2b4ba683019074334678d364dd81cc7ab939f453c6418f6a6f8556142685cf00fb7c65675912416
+  metadata.gz: bd622ed113b4cc6c1cf8bcebc612785bc5a6ee549daa6a83b7d74df236eefe9beffac0a81867ad54053b7a2761e24e7687e8de96d0004e11e94cc9a34050d39c
+  data.tar.gz: bfed9ad01ac4d045eb61d01bf4effbfa45b2c89839daa9faf58542afd5dbc2268d8c124f85c6d659e8d2d620ce9548a4c39d5d797fbf32ebe8f00e4c9092adf9

data/README.md

@@ -18,6 +18,7 @@ A Rack middleware captures object allocations for every request using `GC.stat`
 - [Installation](#installation)
 - [Dashboard](#dashboard)
 - [Configuration](#configuration)
+- [Compatibility](#compatibility)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -121,9 +122,20 @@ expect { MyClass.new }.to allocate_fewer_than(500)
 
 ---
 
+## Compatibility
+
+|          | Ruby 3.3 | Ruby 3.4 | Ruby 4.0 |
+|----------|:--------:|:--------:|:--------:|
+| Rails 7.1 | ✓ | ✓ | ✓ |
+| Rails 8.x | ✓ | ✓ | ✓ |
+
+[↑ Back to top](#railsmemoryprofiler)
+
+---
+
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/eclectic-coding/rails_memory_profiler).
+Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 [↑ Back to top](#railsmemoryprofiler)
 

data/app/controllers/rails_memory_profiler/reports_controller.rb

@@ -15,11 +15,6 @@ module RailsMemoryProfiler
       end
     end
 
-    def clear
-      ReportStore.clear
-      redirect_to reports_path
-    end
-
     def show
       @report = ReportStore.find(params[:id])
 

data/app/controllers/rails_memory_profiler/store_controller.rb

@@ -0,0 +1,8 @@
+module RailsMemoryProfiler
+  class StoreController < BaseController
+    def destroy
+      ReportStore.clear
+      redirect_to reports_path
+    end
+  end
+end

data/app/views/rails_memory_profiler/reports/index.html.erb

@@ -5,7 +5,7 @@
       <p><%= @reports.size %> request<%= "s" unless @reports.size == 1 %> captured</p>
     </div>
     <% unless @reports.empty? %>
-      <%= button_to "Clear All", clear_reports_path, method: :delete,
+      <%= button_to "Clear All", store_path, method: :delete,
             class: "rmp-btn-danger",
             form: { data: { turbo_confirm: "Clear all reports? This cannot be undone." } } %>
     <% end %>

data/config/routes.rb

@@ -1,8 +1,5 @@
 RailsMemoryProfiler::Engine.routes.draw do
-  resources :reports, only: [:index, :show] do
-    collection do
-      delete :clear
-    end
-  end
-  resource :comparison, only: [:show]
+  resources :reports, only: [:index, :show]
+  resource  :comparison, only: [:show]
+  resource  :store,      only: [:destroy], controller: "store"
 end

data/lib/rails_memory_profiler/configuration.rb

@@ -1,5 +1,68 @@
 module RailsMemoryProfiler
+  # Holds all user-facing settings. Obtain the shared instance via
+  # {RailsMemoryProfiler.config} or set values inside a {RailsMemoryProfiler.configure} block.
+  #
+  # @example
+  #   RailsMemoryProfiler.configure do |config|
+  #     config.sample_rate           = 5
+  #     config.min_allocated_objects = 1_000
+  #     config.notifiers             = [RailsMemoryProfiler::Notifiers::Console.new]
+  #   end
   class Configuration
+    # @!attribute enabled
+    #   Enable or disable per-request profiling. Defaults to +true+ in development.
+    #   @return [Boolean]
+
+    # @!attribute sample_rate
+    #   Profile every Nth request. +1+ profiles every request.
+    #   @return [Integer]
+
+    # @!attribute store_size
+    #   Maximum number of reports kept in the ring buffer. Oldest are evicted when full.
+    #   @return [Integer]
+
+    # @!attribute dashboard_enabled
+    #   Enable the HTML/JSON dashboard endpoint. Defaults to +true+ in development.
+    #   @return [Boolean]
+
+    # @!attribute min_allocated_objects
+    #   Skip recording requests that allocate fewer objects than this threshold.
+    #   @return [Integer]
+
+    # @!attribute ignore_paths
+    #   Paths to skip entirely. Accepts strings (prefix match) or Regexps.
+    #   The engine's own mount path is always ignored regardless of this setting.
+    #   @return [Array<String, Regexp>]
+
+    # @!attribute ignore_controllers
+    #   Controller names to skip (matched against the Rails controller name string).
+    #   @return [Array<String>]
+
+    # @!attribute detailed_reports
+    #   Capture full +MemoryProfiler.report+ breakdowns (by gem, class, file, location).
+    #   Requires +gem "memory_profiler"+ in the host app's Gemfile.
+    #   @return [Boolean]
+
+    # @!attribute detailed_sample_rate
+    #   When {#detailed_reports} is enabled, capture a full report every Nth profiled request.
+    #   @return [Integer]
+
+    # @!attribute raise_on_allocation_spike
+    #   Raise {RailsMemoryProfiler::AllocationSpikeError} when allocated objects exceed this value.
+    #   Set to +nil+ to disable. Intended for use in test environments.
+    #   @return [Integer, nil]
+
+    # @!attribute notifiers
+    #   Array of notifier objects, each responding to +#call(report)+. Called after
+    #   each report is stored. Built-in options: {Notifiers::Logger}, {Notifiers::Stdout},
+    #   {Notifiers::Console}, {Notifiers::FileLogger}.
+    #   @return [Array<#call>]
+
+    # @!attribute log_file
+    #   Path to a file where reports are appended as JSON lines. Shortcut for
+    #   configuring {Notifiers::FileLogger} manually.
+    #   @return [String, nil]
+
     attr_accessor :enabled, :sample_rate, :store_size, :dashboard_enabled,
                   :min_allocated_objects, :ignore_paths, :ignore_controllers,
                   :detailed_reports, :detailed_sample_rate,

data/lib/rails_memory_profiler/engine.rb

@@ -6,18 +6,35 @@ module RailsMemoryProfiler
     isolate_namespace RailsMemoryProfiler
     config.generators.api_only = true
 
+    MOUNT_PATH_MUTEX = Mutex.new
+    private_constant :MOUNT_PATH_MUTEX
+
     class << self
+      # Returns the path at which the engine is mounted in the host application,
+      # e.g. +"/rails/memory"+. Detected lazily on first call by scanning
+      # +Rails.application.routes+, then cached. Returns +nil+ if the engine is
+      # not mounted.
+      #
+      # @return [String, nil]
       def mount_path
-        @mount_path ||= begin
-          mounted = Rails.application.routes.routes.find do |route|
-            route.app.app == self rescue false
+        return @mount_path if @mount_path
+
+        MOUNT_PATH_MUTEX.synchronize do
+          @mount_path ||= begin
+            mounted = Rails.application.routes.routes.find do |route|
+              route.app.app == self rescue false
+            end
+            mounted&.path&.spec&.to_s&.gsub(/\([^)]*\)/, "")
           end
-          mounted&.path&.spec&.to_s&.gsub(/\([^)]*\)/, "")
         end
       end
 
+      # Clears the cached mount path so it will be re-detected on the next call.
+      # Primarily used in tests.
+      #
+      # @return [void]
       def reset_mount_path!
-        @mount_path = nil
+        MOUNT_PATH_MUTEX.synchronize { @mount_path = nil }
       end
     end
 

data/lib/rails_memory_profiler/middleware.rb

@@ -1,5 +1,14 @@
 module RailsMemoryProfiler
+  # Rack middleware that profiles each request and pushes a report into {ReportStore}.
+  # Registered automatically by the {Engine} initializer; you do not need to add it
+  # to the middleware stack manually.
+  #
+  # Profiling is skipped when:
+  # - {Configuration#enabled} is +false+
+  # - the request path matches {Configuration#ignore_paths} or the engine mount path
+  # - the request is not selected by {Configuration#sample_rate}
   class Middleware
+    # @param app [#call] the next Rack application in the stack
     def initialize(app)
       @app            = app
       @request_count  = 0
@@ -7,6 +16,10 @@ module RailsMemoryProfiler
       @mutex          = Mutex.new
     end
 
+    # Profiles the request if applicable and delegates to the inner app.
+    #
+    # @param env [Hash] Rack environment
+    # @return [Array] Rack response triplet
     def call(env)
       return @app.call(env) unless RailsMemoryProfiler.config.enabled
       return @app.call(env) if ignored_path?(env["PATH_INFO"])

data/lib/rails_memory_profiler/report_store.rb

@@ -1,6 +1,25 @@
 module RailsMemoryProfiler
+  # Thread-safe circular buffer that holds per-request profiling reports.
+  # Capacity is controlled by {Configuration#store_size}. When full, the oldest
+  # report is evicted to make room for each new one.
+  #
+  # Each report is a Hash with the keys:
+  # - +:id+ — unique hex string assigned on push
+  # - +:path+, +:method+, +:controller+, +:action+
+  # - +:allocated_objects+, +:retained_objects+
+  # - +:duration_ms+
+  # - +:recorded_at+ — +Time+ of capture
+  # - +:detail+ — optional breakdown Hash (present when {Configuration#detailed_reports} is enabled)
   module ReportStore
+    MUTEX = Mutex.new
+    private_constant :MUTEX
+
     class << self
+      # Adds a report to the buffer, assigning a unique +:id+ key.
+      # Evicts the oldest entry when the buffer is at capacity.
+      #
+      # @param report [Hash] profiling data without an +:id+ key
+      # @return [void]
       def push(report)
         mutex.synchronize do
           ensure_buffer_size
@@ -10,10 +29,17 @@ module RailsMemoryProfiler
         end
       end
 
+      # Returns the report with the given id, or +nil+ if not found or evicted.
+      #
+      # @param id [String]
+      # @return [Hash, nil]
       def find(id)
         all.find { |r| r[:id] == id }
       end
 
+      # Returns all stored reports in insertion order (oldest first).
+      #
+      # @return [Array<Hash>]
       def all
         mutex.synchronize do
           stored = @stored || 0
@@ -27,10 +53,16 @@ module RailsMemoryProfiler
         end
       end
 
+      # Removes all stored reports.
+      #
+      # @return [void]
       def clear
         mutex.synchronize { reset! }
       end
 
+      # Returns the number of reports currently stored.
+      #
+      # @return [Integer]
       def size
         mutex.synchronize { @stored || 0 }
       end
@@ -38,7 +70,7 @@ module RailsMemoryProfiler
       private
 
         def mutex
-          @mutex ||= Mutex.new
+          MUTEX
         end
 
         def capacity

data/lib/rails_memory_profiler/test_helper.rb

@@ -1,9 +1,25 @@
 require "rails_memory_profiler"
 
 module RailsMemoryProfiler
+  # Utility methods for asserting allocation counts in tests.
+  # Not auto-required — opt in with:
+  #
+  #   require "rails_memory_profiler/test_helper"
+  #
+  # Works as a module-level call or mixed into a test class via +include+/+extend+:
+  #
+  #   include RailsMemoryProfiler::TestHelper
+  #
+  # For RSpec block expectations see {file:lib/rails_memory_profiler/rspec_matchers.rb}.
+  # For Minitest assertions see {file:lib/rails_memory_profiler/minitest_matchers.rb}.
   module TestHelper
     extend self
 
+    # Runs the block and returns the number of Ruby objects allocated during it.
+    # Triggers a full GC before measuring to reduce noise from prior allocations.
+    #
+    # @yieldreturn [Object] the block's return value is discarded
+    # @return [Integer] number of objects allocated
     def capture_allocations
       GC.start
       before = GC.stat(:total_allocated_objects)
@@ -11,6 +27,15 @@ module RailsMemoryProfiler
       GC.stat(:total_allocated_objects) - before
     end
 
+    # Asserts that the block allocates fewer than +threshold+ objects.
+    # Raises +Minitest::Assertion+ when Minitest is loaded (so the failure is
+    # reported as a test failure rather than an error), otherwise raises +RuntimeError+.
+    #
+    # @param threshold [Integer] maximum acceptable allocation count
+    # @yieldreturn [Object] the block's return value is discarded
+    # @raise [Minitest::Assertion] when Minitest is present and the threshold is exceeded
+    # @raise [RuntimeError] when Minitest is absent and the threshold is exceeded
+    # @return [void]
     def assert_allocations_below(threshold, &block)
       count = capture_allocations(&block)
       return if count < threshold

data/lib/rails_memory_profiler/version.rb

@@ -1,3 +1,3 @@
 module RailsMemoryProfiler
-  VERSION = "0.5.0"
+  VERSION = "1.0.0"
 end

data/lib/rails_memory_profiler.rb

@@ -5,20 +5,54 @@ require "rails_memory_profiler/notifiers"
 require "rails_memory_profiler/middleware"
 require "rails_memory_profiler/engine"
 
+# RailsMemoryProfiler is a Rails engine that captures per-request object
+# allocations via GC.stat diffs and serves them through a mountable dashboard.
+#
+# @example Mounting the engine
+#   # config/routes.rb
+#   mount RailsMemoryProfiler::Engine, at: "/rails/memory"
+#
+# @example Configuring the gem
+#   RailsMemoryProfiler.configure do |config|
+#     config.sample_rate           = 5
+#     config.min_allocated_objects = 1_000
+#   end
 module RailsMemoryProfiler
+  # Raised by the middleware when allocated objects exceed
+  # {Configuration#raise_on_allocation_spike}.
   class AllocationSpikeError < StandardError; end
 
   class << self
+    # Yields the {Configuration} instance for block-style setup.
+    #
+    # @yieldparam config [Configuration]
+    # @return [void]
     def configure
       yield config
     end
 
+    # Returns the shared {Configuration} instance, creating it on first call.
+    #
+    # @return [Configuration]
     def config
       @config ||= Configuration.new
     end
 
+    # Replaces the shared {Configuration} instance with a fresh default.
+    # Primarily used in tests.
+    #
+    # @return [Configuration]
     def reset_config!
       @config = Configuration.new
     end
+
+    # Returns a memoized +ActiveSupport::Deprecation+ instance scoped to this
+    # gem. Use it to emit deprecation warnings for any future breaking changes
+    # rather than calling +warn+ directly.
+    #
+    # @return [ActiveSupport::Deprecation]
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("1.0.0", "RailsMemoryProfiler")
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_memory_profiler
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -74,6 +74,7 @@ files:
 - app/controllers/rails_memory_profiler/base_controller.rb
 - app/controllers/rails_memory_profiler/comparisons_controller.rb
 - app/controllers/rails_memory_profiler/reports_controller.rb
+- app/controllers/rails_memory_profiler/store_controller.rb
 - app/helpers/rails_memory_profiler/application_helper.rb
 - app/javascript/rails_memory_profiler/application.js
 - app/javascript/rails_memory_profiler/controllers/application.js