require-profiler 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5b1e34052677db0605367fd1940681029cffc965f7d1db3604e6964ee95a41a
-  data.tar.gz: acbc21ea3bbd7e120bf328287b216fc68ca7be9beb41260925bbca3a70c712cf
+  metadata.gz: 787aa181e1f018e66c9f8163837af8980a0549a23102361206451ca4c640675e
+  data.tar.gz: a7a0a01e40938642a7bd2b505ae18e47e42b3f00fa482c63151c5616d8f746d6
 SHA512:
-  metadata.gz: 67480173af46da1a7dba97b15f5a252b66b20504af35a1397f66662dc65e97e64381419d0d175a71aba3d99d8646ad0be482e3423de72ca4ef4c822b49c6cb28
-  data.tar.gz: e91be6bf3e684cfb9c969e2bfa495ba71b1a782dddfa4cdaa1f9c3d7573047c50dd3b0a308c377996b4405e1f38f32c8604eea5993e7c6b0a8369ec27044515e
+  metadata.gz: f99d748f75f3333f90979bfde8082591bb77e6b56590df2424dc566ff556798a50660d2c125d4b261c37235b0cdc95ff7cf228f146bd1e8f27d88af5498d90a3
+  data.tar.gz: b0b8aa77547e9852c91f699944877450aa03d125f4324b2efc5ea59854c293680215ee8bf272eda892a7c90c33ee5422bdecbeb3c6cf4530e2389a0aa1da8e05

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## master
 
+## 0.2.0 (2026-05-25) 🔔
+
+- Add ability to run Stackprof for a particular file loading. ([@palkan][])
+
+- Add focus support (to include only matching files). ([@palkan][])
+
+- Add threshold support (`REQUIRE_PROFILE_THRESHOLD`). ([@palkan][])
+
+- Add `-require-prof` support. ([@palkan][])
+
+- Support passing format and output path via `REQUIRE_PROFILE_FORMAT` and `REQUIRE_PROFILE_PATH`. ([@palkan][])
+
+## 0.1.1 (2026-04-29)
+
+- Fix JSON printer leaving trailing call-stack bytes in output. ([@ardecvz][])
+
+We overwrite the buffered call-stack text with a (shorter) Speedscope JSON document but never truncate it, breaking JSON validity.
+
+Truncate the file properly.
+
 ## 0.1.0 (2026-04-22)
 
 - Initial
+
+[@palkan]: https://github.com/palkan
+[@ardecvz]: https://github.com/ardecvz

data/README.md

@@ -24,6 +24,48 @@ gem "require-profiler"
 
 ## Usage
 
+### Using `-require-prof` command switch
+
+Given that `require-profiler` is a part of your bundle (or available globally), you can enable it as follows:
+
+```sh
+# Without Bundler
+ruby -require-prof some_ruby_script.rb
+
+# With Bundler
+ruby -rbundler/setup -require-prof some_ruby_script.rb
+```
+
+For Rails applications, the command will look like:
+
+```sh
+bundle exec ruby -r./config/boot -require-prof config/environment.rb
+```
+
+We load the `config/boot.rb` file first to set up Bundler and **Bootsnap** (it must be required before require-hooks).
+
+You can use environment variables to specify the output format and path. For example:
+
+```sh
+REQUIRE_PROFILE_PATH=tmp/require-prof.json bundle exec ruby -r./config/boot -require-prof config/environment.rb
+```
+
+You can also specify the threshold to display only files taking at least the provided number of milliseconds to load:
+
+```sh
+REQUIRE_PROFILE_THRESHOLD=100 bundle exec ruby -r./config/boot -require-prof config/environment.rb
+```
+
+Or file matching the provided _focus_ pattern:
+
+```sh
+REQUIRE_PROFILE_FOCUS=stripe bundle exec ruby -r./config/boot -require-prof config/environment.rb
+```
+
+### Programmable usage
+
+If you code loading process is more complicated, you can manually start and stop the profiler from your application.
+
 Wrap the code you want to profile with `RequireProfiler.start` and `RequireProfiler.stop`:
 
 ```ruby
@@ -49,12 +91,30 @@ RequireProfiler.start(
 )
 ```
 
-### Output
+### Ruby profilers integration
+
+Whenever you identified the files that take a long time to load, it's useful to look at them closer and profile the load process using some generic profiler. Require Profiler simplifies this down to the environment variable usage. This is, for example, how you can profile the loading of an initializer file via StackProf:
+
+```sh
+$ REQUIRE_PROFILE_STACKPROF=config/initializers/fragment.rb REQUIRE_PROFILE_THRESHOLD=100 be ruby -r./config/boot -require-prof config/environment.rb
+
+...
+Stackprof JSON profile for config/initializers/fragment.rb is generated: config-initializers-fragment-stackprof.json
+...
+
+```
+
+Now you can use Speedscope to dig deeper.
+
+**NOTE:** The `stackprof` gem must be present in your Gemfile for that.
+
+### Configuration
 
 `RequireProfiler.start` accepts the following keyword arguments:
 
 - `output:` — `$stdout` (default), any IO-like object, or a file path (string).
-- `format:` — `:text` (default), `:call_stack`, or `:json`. When `output:` is a file path with a `.json` extension, the JSON format is picked automatically.
+- `format:` — `:text` (default), `:call_stack`, or `:json`. When `output:` is a file path with a `.json` extension, the JSON format is picked automatically. You can also provide format via the `REQUIRE_PROFILE_FORMAT` env var.
+- `threshold:` — the number of **milliseconds** to use as a threshold to ignore files taking less to load, float. Default is 0.0
 - `patterns:` / `exclude_patterns:` — see above.
 
 ## Output formats

data/lib/equire-prof.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "require_profiler"
+
+RequireProfiler.start
+at_exit { RequireProfiler.stop }

data/lib/require_profiler/printer/call_stack.rb

@@ -5,6 +5,8 @@ module RequireProfiler
     # CallStack formatter prints collapsed stacks (Brendan Gregg's format)
     class CallStack < Base
       def flush(node, parts: [])
+        return unless flush?(node)
+
         path = node.path.sub(prefix_stripper, "")
         self_parts = path.split("/")
 

data/lib/require_profiler/printer/json.rb

@@ -59,6 +59,7 @@ module RequireProfiler
         }
 
         output.write(::JSON.pretty_generate(profile))
+        output.truncate(output.pos)
         super
       end
     end

data/lib/require_profiler/printer/text.rb

@@ -6,6 +6,8 @@ module RequireProfiler
       PAD = "  "
 
       def flush(node, indent: 0)
+        return unless flush?(node)
+
         path = node.path.sub(prefix_stripper, "")
         output << "#{PAD * indent}#{path} — #{time_to_duration(node.time)}\n"
         node.children.each { flush(_1, indent: indent + 1) }

data/lib/require_profiler/printer.rb

@@ -3,11 +3,13 @@
 module RequireProfiler
   module Printer
     class Base
-      private attr_reader :output
+      private attr_reader :output, :threshold, :focus
       private attr_reader :prefix_stripper
 
-      def initialize(output)
+      def initialize(output, threshold: 0.0, focus: nil)
         @output = output
+        @threshold = threshold
+        @focus = focus
 
         # Identify prefixes for the project and the gems
         prefixes = [::Dir.pwd]
@@ -24,6 +26,16 @@ module RequireProfiler
       def finish
         output.close if output.respond_to?(:close) && output != $stdout
       end
+
+      private
+
+      def flush?(node)
+        return false unless (node.time * 1000) >= threshold
+
+        return false if focus && !node.focused
+
+        true
+      end
     end
 
     autoload :Text, "require_profiler/printer/text"
@@ -31,14 +43,14 @@ module RequireProfiler
     autoload :JSON, "require_profiler/printer/json"
 
     class << self
-      def resolve(output, format)
+      def resolve(output, format, **opts)
         format ||= (output.is_a?(String) && File.extname(output) == ".json") ? :json : :text
         output = File.open(output, "w+") if output.is_a?(String)
 
         case format.to_sym
-        when :json then JSON.new(output)
-        when :call_stack then CallStack.new(output)
-        when :text then Text.new(output)
+        when :json then JSON.new(output, **opts)
+        when :call_stack then CallStack.new(output, **opts)
+        when :text then Text.new(output, **opts)
         else
           raise ArgumentError, "Unknown format specified: #{format}. Available formats: text, json, call_stack"
         end

data/lib/require_profiler/reporter.rb

@@ -5,19 +5,26 @@ module RequireProfiler
     class Event < Struct.new(:type, :path, :time, keyword_init: true)
     end
 
-    class Node < Struct.new(:path, :time, :children, keyword_init: true)
+    class Node < Struct.new(:path, :time, :parent, :children, :focused, keyword_init: true)
       def initialize(...)
         super
         self.children ||= []
+        self.focused = false
+      end
+
+      def focused!
+        self.focused = true
+        parent&.focused!
       end
     end
 
-    private attr_reader :stack, :totals, :printer, :processor, :queue
+    private attr_reader :stack, :totals, :printer, :processor, :queue, :focus
 
-    def initialize(printer:)
+    def initialize(printer:, focus: nil)
       @stack = []
       @totals = {count: 0, time: 0.0}
       @printer = printer
+      @focus = focus
       @processor = nil
       @queue = Queue.new
 
@@ -31,13 +38,20 @@ module RequireProfiler
     def handle_event_sync(event)
       if event.type == :start
         node = Node.new(path: event.path, children: [])
-        stack.last&.children&.push(node)
+        parent = stack.last
+
+        if parent
+          node.parent = parent
+          parent.children&.push(node)
+        end
 
         stack << node
       elsif event.type == :end
         last = stack.pop
         last.time = event.time
 
+        last.focused! if focus && last.path.match?(focus)
+
         printer.flush(last) if stack.empty?
 
         totals[:count] += 1

data/lib/require_profiler/ruby_profiling.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  # This module contains helpers to activate specific files loading
+  # profiling using Stackprof or Vernier (so you can dig deeper into why a particular
+  # file is slow to require)
+  module RubyProfiling
+    class << self
+      attr_accessor :enabled, :target_path, :profiler
+
+      def enabled?
+        @enabled
+      end
+
+      def capture(path, &)
+        return yield unless path.end_with?(target_path)
+
+        if profiler == :stackprof
+          capture_stackprof(path, &)
+        end
+      end
+
+      private
+
+      def capture_stackprof(path)
+        require "stackprof"
+
+        filename = target_path.sub(/\.rb$/, "").tr("/.", "-") + "-stackprof"
+        dump_path = filename + ".dump"
+
+        options = {
+          mode: :wall,
+          raw: true,
+          out: dump_path
+        }
+
+        ::StackProf.run(**options) { yield }.tap do
+          report = ::StackProf::Report.new(
+            Marshal.load(IO.binread(dump_path))
+          )
+          json_path = filename + ".json"
+          File.write(json_path, JSON.generate(report.data))
+          $stdout.puts "Stackprof JSON profile for #{target_path} is generated: #{json_path}"
+        end
+      end
+    end
+
+    if ENV["REQUIRE_PROFILE_STACKPROF"]
+      self.enabled = true
+      self.target_path = ENV["REQUIRE_PROFILE_STACKPROF"]
+      self.profiler = :stackprof
+    end
+  end
+end

data/lib/require_profiler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RequireProfiler # :nodoc:
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/require_profiler.rb

@@ -4,13 +4,23 @@ module RequireProfiler
   autoload :Reporter, "require_profiler/reporter"
   autoload :Printer, "require_profiler/printer"
 
+  # Autoload doesn't work here, because we call it from the hooks for the first time
+  require "require_profiler/ruby_profiling"
+
   class << self
     attr_reader :reporter
 
-    def start(output: $stdout, format: nil, patterns: nil, exclude_patterns: nil)
+    def start(
+      output: ENV.fetch("REQUIRE_PROFILE_PATH", $stdout),
+      format: ENV["REQUIRE_PROFILE_FORMAT"],
+      threshold: ENV.fetch("REQUIRE_PROFILE_THRESHOLD", "0.0").to_f,
+      focus: ENV["REQUIRE_PROFILE_FOCUS"],
+      patterns: nil, exclude_patterns: nil
+    )
       raise ArgumentError, "There is already profiling in progress" if reporter
 
-      reporter = @reporter = Reporter.new(printer: Printer.resolve(output, format))
+      focus = Regexp.new(focus) if focus.is_a?(String)
+      reporter = @reporter = Reporter.new(printer: Printer.resolve(output, format, threshold:, focus:), focus:)
 
       require "require-hooks/setup"
 
@@ -19,7 +29,11 @@ module RequireProfiler
 
         reporter.handle_event(Reporter::Event.new(type: :start, path:))
 
-        block.call
+        if RubyProfiling.enabled?
+          RubyProfiling.capture(path) { block.call }
+        else
+          block.call
+        end
       ensure
         time = Time.now - start
         reporter.handle_event(Reporter::Event.new(type: :end, path:, time:))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: require-profiler
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Vladimir Dementyev
@@ -75,6 +75,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/equire-prof.rb
 - lib/require-profiler.rb
 - lib/require_profiler.rb
 - lib/require_profiler/printer.rb
@@ -82,6 +83,7 @@ files:
 - lib/require_profiler/printer/json.rb
 - lib/require_profiler/printer/text.rb
 - lib/require_profiler/reporter.rb
+- lib/require_profiler/ruby_profiling.rb
 - lib/require_profiler/version.rb
 homepage: https://github.com/palkan/require-profiler
 licenses: