rails_memory_profiler 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6f3720c5cac0f1ec3299a0e54a621acb6c2f5881b8b76ca9b737df70cc29cad
-  data.tar.gz: 7180cecd1e284b10521c1736c5f0aff6f4bc4811e3ac812a06d7d8e97d7bf4d0
+  metadata.gz: da1c19f27cafbf571c7f5fe0e724c56e305d81307c99c1d970fdc96777459888
+  data.tar.gz: d95173a0c57ec1afefc7a13eed43e06b5fef53a8350a3b5b2955f42ad01c382f
 SHA512:
-  metadata.gz: e827b8dcbb33b723b2f557e93ef6b16dcbd062e18049e9ccb98bc0df3268318155f30594b124a6166547951eee3a79c1bff2d02a931c3193de6bd86940d98f6b
-  data.tar.gz: c3522a8f0c3fe3a0d2c6fcb689f41203aa1267829509aa9ca123b185d9451f3347530724f33e17555736d91f8a5346e55a15834d4156c7f76a50030fd8100a5f
+  metadata.gz: c34cfa6505349cae21f6e808c55bd8c682456809ac3052ed2d67ed72099ec72f4cfd890653c36cf580d15f92c9988b1a94ce95dfa679c1cda1fb4f2fefa51747
+  data.tar.gz: e5e1c2f7194e48d82b0073aed382662f95ffb552e119993a25dd62a58285f5a89e31e600664928a7bcd515696a5abebc2f02d32d9a49df5a5124d7c38c5165b6

data/README.md

@@ -78,6 +78,9 @@ All options and their defaults:
 | `ignore_controllers` | `[]` | Controller names to skip (e.g. `"rails/health"`) |
 | `detailed_reports` | `false` | Capture full `MemoryProfiler.report` breakdowns; requires `gem "memory_profiler"` in your Gemfile |
 | `detailed_sample_rate` | `10` | When `detailed_reports` is enabled, capture a full report every Nth profiled request |
+| `notifiers` | `[]` | Array of objects responding to `#call(report)`; called after each report is stored |
+| `log_file` | `nil` | Path to append JSON-serialized reports (one per line); shortcut for `Notifiers::FileLogger` |
+| `raise_on_allocation_spike` | `nil` | Raise `AllocationSpikeError` when `allocated_objects` exceeds this threshold |
 
 Example:
 
@@ -87,9 +90,26 @@ RailsMemoryProfiler.configure do |config|
   config.min_allocated_objects = 1_000
   config.ignore_paths          = ["/rails/memory", "/up"]
   config.ignore_controllers    = ["rails/health"]
+  config.notifiers             = [RailsMemoryProfiler::Notifiers::Console.new]
+  config.log_file              = Rails.root.join("log/memory_profiler.jsonl")
 end
 ```
 
+### Test helpers
+
+```ruby
+# Minitest / plain Ruby
+require "rails_memory_profiler/test_helper"
+
+count = RailsMemoryProfiler::TestHelper.capture_allocations { MyClass.new }
+RailsMemoryProfiler::TestHelper.assert_allocations_below(500) { MyClass.new }
+
+# RSpec
+require "rails_memory_profiler/rspec_matchers"
+
+expect { MyClass.new }.to allocate_fewer_than(500)
+```
+
 [↑ Back to top](#railsmemoryprofiler)
 
 ---

data/lib/generators/rails_memory_profiler/install/templates/initializer.rb

@@ -32,4 +32,18 @@ RailsMemoryProfiler.configure do |config|
 
   # When detailed_reports is enabled, capture a full report every Nth profiled request.
   # config.detailed_sample_rate = 10
+
+  # Notifiers — called after each report is stored. Each must respond to #call(report).
+  # Built-in options:
+  #   RailsMemoryProfiler::Notifiers::Logger.new   — writes to Rails.logger
+  #   RailsMemoryProfiler::Notifiers::Stdout.new   — writes to $stdout
+  #   RailsMemoryProfiler::Notifiers::Console.new  — colorized terminal output
+  # config.notifiers = [RailsMemoryProfiler::Notifiers::Logger.new]
+
+  # Append JSON-serialized reports to a file (one report per line).
+  # config.log_file = Rails.root.join("log/memory_profiler.log").to_s
+
+  # Raise AllocationSpikeError when a request exceeds this many allocated objects.
+  # Useful in test environments to catch unexpected memory spikes.
+  # config.raise_on_allocation_spike = nil
 end

data/lib/rails_memory_profiler/configuration.rb

@@ -2,7 +2,9 @@ module RailsMemoryProfiler
   class Configuration
     attr_accessor :enabled, :sample_rate, :store_size, :dashboard_enabled,
                   :min_allocated_objects, :ignore_paths, :ignore_controllers,
-                  :detailed_reports, :detailed_sample_rate
+                  :detailed_reports, :detailed_sample_rate,
+                  :raise_on_allocation_spike,
+                  :notifiers, :log_file
 
     def initialize
       @enabled               = Rails.env.development?
@@ -12,8 +14,11 @@ module RailsMemoryProfiler
       @min_allocated_objects = 0
       @ignore_paths          = []
       @ignore_controllers    = []
-      @detailed_reports      = false
-      @detailed_sample_rate  = 10
+      @detailed_reports          = false
+      @detailed_sample_rate      = 10
+      @raise_on_allocation_spike = nil
+      @notifiers                 = []
+      @log_file                  = nil
     end
   end
 end

data/lib/rails_memory_profiler/middleware.rb

@@ -93,6 +93,23 @@ module RailsMemoryProfiler
         payload[:detail] = detail if detail
 
         ReportStore.push(payload)
+        notify!(payload)
+        check_spike!(allocated_objects, env)
+      end
+
+      def notify!(report)
+        RailsMemoryProfiler.config.notifiers.each { |n| n.call(report) }
+        if (path = RailsMemoryProfiler.config.log_file)
+          Notifiers::FileLogger.new(path).call(report)
+        end
+      end
+
+      def check_spike!(allocated_objects, env)
+        threshold = RailsMemoryProfiler.config.raise_on_allocation_spike
+        return unless threshold && allocated_objects > threshold
+
+        raise AllocationSpikeError,
+          "#{env['PATH_INFO']} allocated #{allocated_objects} objects (threshold: #{threshold})"
       end
 
       def serialize_stats(stats)

data/lib/rails_memory_profiler/notifiers/console.rb

@@ -0,0 +1,36 @@
+module RailsMemoryProfiler
+  module Notifiers
+    class Console
+      RESET  = "\e[0m"
+      CYAN   = "\e[36m"
+      DIM    = "\e[2m"
+      GREEN  = "\e[32m"
+      YELLOW = "\e[33m"
+      RED    = "\e[31m"
+
+      def call(report)
+        $stdout.puts(colorize(report))
+      end
+
+      private
+
+        def colorize(report)
+          action = [report[:controller], report[:action]].compact.join("#")
+          alloc  = report[:allocated_objects]
+
+          "#{DIM}[RMP]#{RESET} " \
+          "#{CYAN}#{report[:method]} #{report[:path]}#{RESET} " \
+          "#{DIM}(#{action})#{RESET}  " \
+          "#{alloc_color(alloc)}#{Notifiers.thousands(alloc)} alloc#{RESET}  " \
+          "#{DIM}#{report[:retained_objects]} retained  #{report[:duration_ms]}ms#{RESET}"
+        end
+
+        def alloc_color(count)
+          if count < 5_000 then GREEN
+          elsif count < 20_000 then YELLOW
+          else RED
+          end
+        end
+    end
+  end
+end

data/lib/rails_memory_profiler/notifiers/file_logger.rb

@@ -0,0 +1,16 @@
+require "json"
+
+module RailsMemoryProfiler
+  module Notifiers
+    class FileLogger
+      def initialize(path)
+        @path = path
+      end
+
+      def call(report)
+        serializable = report.merge(recorded_at: report[:recorded_at]&.iso8601)
+        File.open(@path, "a") { |f| f.puts(serializable.to_json) }
+      end
+    end
+  end
+end

data/lib/rails_memory_profiler/notifiers/logger.rb

@@ -0,0 +1,9 @@
+module RailsMemoryProfiler
+  module Notifiers
+    class Logger
+      def call(report)
+        Rails.logger.info(Notifiers.format_line(report))
+      end
+    end
+  end
+end

data/lib/rails_memory_profiler/notifiers/stdout.rb

@@ -0,0 +1,9 @@
+module RailsMemoryProfiler
+  module Notifiers
+    class Stdout
+      def call(report)
+        $stdout.puts(Notifiers.format_line(report))
+      end
+    end
+  end
+end

data/lib/rails_memory_profiler/notifiers.rb

@@ -0,0 +1,19 @@
+require "rails_memory_profiler/notifiers/logger"
+require "rails_memory_profiler/notifiers/stdout"
+require "rails_memory_profiler/notifiers/console"
+require "rails_memory_profiler/notifiers/file_logger"
+
+module RailsMemoryProfiler
+  module Notifiers
+    def self.format_line(report)
+      action = [report[:controller], report[:action]].compact.join("#")
+      "[RailsMemoryProfiler] #{report[:method]} #{report[:path]} (#{action})" \
+        " — #{thousands(report[:allocated_objects])} allocated," \
+        " #{report[:retained_objects]} retained, #{report[:duration_ms]}ms"
+    end
+
+    def self.thousands(n)
+      n.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+    end
+  end
+end

data/lib/rails_memory_profiler/rspec_matchers.rb

@@ -0,0 +1,20 @@
+require "rails_memory_profiler/test_helper"
+
+if defined?(RSpec)
+  RSpec::Matchers.define :allocate_fewer_than do |expected|
+    supports_block_expectations
+
+    match do |block|
+      @count = RailsMemoryProfiler::TestHelper.capture_allocations(&block)
+      @count < expected
+    end
+
+    failure_message do
+      "expected block to allocate fewer than #{expected} objects, but got #{@count}"
+    end
+
+    failure_message_when_negated do
+      "expected block to allocate #{expected} or more objects, but got #{@count}"
+    end
+  end
+end

data/lib/rails_memory_profiler/test_helper.rb

@@ -0,0 +1,21 @@
+require "rails_memory_profiler"
+
+module RailsMemoryProfiler
+  module TestHelper
+    extend self
+
+    def capture_allocations
+      GC.start
+      before = GC.stat(:total_allocated_objects)
+      yield
+      GC.stat(:total_allocated_objects) - before
+    end
+
+    def assert_allocations_below(threshold, &block)
+      count = capture_allocations(&block)
+      return if count < threshold
+
+      raise "Expected fewer than #{threshold} allocated objects but got #{count}"
+    end
+  end
+end

data/lib/rails_memory_profiler/version.rb

@@ -1,3 +1,3 @@
 module RailsMemoryProfiler
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/rails_memory_profiler.rb

@@ -2,10 +2,13 @@ require "rails_memory_profiler/version"
 require "rails_memory_profiler/configuration"
 require "rails_memory_profiler/request_context"
 require "rails_memory_profiler/report_store"
+require "rails_memory_profiler/notifiers"
 require "rails_memory_profiler/middleware"
 require "rails_memory_profiler/engine"
 
 module RailsMemoryProfiler
+  class AllocationSpikeError < StandardError; end
+
   class << self
     def configure
       yield config

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_memory_profiler
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -96,8 +96,15 @@ files:
 - lib/rails_memory_profiler/configuration.rb
 - lib/rails_memory_profiler/engine.rb
 - lib/rails_memory_profiler/middleware.rb
+- lib/rails_memory_profiler/notifiers.rb
+- lib/rails_memory_profiler/notifiers/console.rb
+- lib/rails_memory_profiler/notifiers/file_logger.rb
+- lib/rails_memory_profiler/notifiers/logger.rb
+- lib/rails_memory_profiler/notifiers/stdout.rb
 - lib/rails_memory_profiler/report_store.rb
 - lib/rails_memory_profiler/request_context.rb
+- lib/rails_memory_profiler/rspec_matchers.rb
+- lib/rails_memory_profiler/test_helper.rb
 - lib/rails_memory_profiler/version.rb
 - lib/tasks/rails_memory_profiler_tasks.rake
 homepage: https://github.com/eclectic-coding/rails_memory_profiler