require-profiler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d5b1e34052677db0605367fd1940681029cffc965f7d1db3604e6964ee95a41a
+  data.tar.gz: acbc21ea3bbd7e120bf328287b216fc68ca7be9beb41260925bbca3a70c712cf
+SHA512:
+  metadata.gz: 67480173af46da1a7dba97b15f5a252b66b20504af35a1397f66662dc65e97e64381419d0d175a71aba3d99d8646ad0be482e3423de72ca4ef4c822b49c6cb28
+  data.tar.gz: e91be6bf3e684cfb9c969e2bfa495ba71b1a782dddfa4cdaa1f9c3d7573047c50dd3b0a308c377996b4405e1f38f32c8604eea5993e7c6b0a8369ec27044515e

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+## master
+
+## 0.1.0 (2026-04-22)
+
+- Initial

data/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2026 Vladimir Dementyev
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,131 @@
+[![Gem Version](https://badge.fury.io/rb/require-profiler.svg)](https://rubygems.org/gems/require-profiler)
+[![Build](https://github.com/palkan/require-profiler/workflows/Build/badge.svg)](https://github.com/palkan/require-profiler/actions)
+
+# Require Profiler
+
+Require Profiler is a tool for profiling Ruby's code loading—`Kernel#require`, `Kernel#require_relative`, and `Kernel#load`. It captures the call tree, measures how long each file takes to load, and can export the results as a [Speedscope][speedscope]-compatible JSON profile.
+
+It's built on top of [Require Hooks][require-hooks], so it works anywhere Require Hooks does (MRI/JRuby/TruffleRuby).
+
+<a href="https://evilmartians.com/">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "require-profiler"
+```
+
+### Supported Ruby versions
+
+- Ruby (MRI) >= 3.1
+
+## Usage
+
+Wrap the code you want to profile with `RequireProfiler.start` and `RequireProfiler.stop`:
+
+```ruby
+require "require_profiler"
+
+RequireProfiler.start(output: "path/to/profile.txt")
+require "my_app"
+RequireProfiler.stop
+```
+
+Only `require`/`load` calls that happen between `.start` and `.stop` are captured. Put `.start` as early as possible (e.g., at the top of `config/boot.rb` or an entry-point script) to see the full loading tree.
+
+`RequireProfiler.stop` returns a totals hash: `{count: <number of files loaded>, time: <seconds>}`.
+
+### Scoping via patterns
+
+Use `patterns:` and `exclude_patterns:` to limit what gets profiled. Both accept globs as recognized by [`File.fnmatch`](https://rubyapi.org/4.0/o/file#method-c-fnmatch) and are passed through to Require Hooks:
+
+```ruby
+RequireProfiler.start(
+  patterns: ["#{Dir.pwd}/app/**/*.rb", "#{Dir.pwd}/lib/**/*.rb"],
+  exclude_patterns: ["*/vendor/*"]
+)
+```
+
+### Output
+
+`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.
+- `patterns:` / `exclude_patterns:` — see above.
+
+## Output formats
+
+### Text (default)
+
+A human-readable indented tree, one line per file, with self+children duration in milliseconds:
+
+```
+lib/my_app.rb — 42.137ms
+  lib/my_app/config.rb — 3.211ms
+  lib/my_app/router.rb — 12.004ms
+    lib/my_app/routes.rb — 9.882ms
+```
+
+Paths are printed relative to `Dir.pwd`, `Gem.dir`, or `Bundler.bundle_path` when they match—so vendored gem loads stay readable.
+
+### Collapsed call stacks
+
+```ruby
+RequireProfiler.start(output: "tmp/require-profile.txt", format: :call_stack)
+```
+
+Emits one line per stack in [Brendan Gregg's collapsed format](https://github.com/brendangregg/FlameGraph#2-fold-stacks) with per-frame self time in milliseconds. Pipe it to `flamegraph.pl`, [`inferno`](https://github.com/jonhoo/inferno), or any tool that consumes folded stacks.
+
+### JSON / Speedscope
+
+```ruby
+RequireProfiler.start(output: "tmp/require-profile.json")
+# or:
+RequireProfiler.start(output: io, format: :json)
+```
+
+Emits a profile that conforms to the [Speedscope file format schema](https://www.speedscope.app/file-format-schema.json).
+
+**Note:** Writing JSON straight to `$stdout` is not supported.
+
+## Using with Speedscope
+
+[Speedscope][speedscope] is an interactive flamegraph viewer that runs entirely in your browser (nothing is uploaded—the file is parsed locally).
+
+1. Generate a JSON profile:
+
+   ```ruby
+   RequireProfiler.start(output: "tmp/require-profile.json")
+   require "my_app"
+   RequireProfiler.stop
+   ```
+
+2. Open [https://www.speedscope.app/](https://www.speedscope.app/) and drag-and-drop `tmp/require-profile.json` onto the page (or use the "Browse" button).
+
+3. Switch to the **Left Heavy** view to see which `require` chains cost the most time, and use **Sandwich** view to find individual files that show up repeatedly.
+
+Prefer to stay local? Install the CLI and it will open a local viewer for you:
+
+```sh
+npm install -g speedscope
+speedscope tmp/require-profile.json
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/require-profiler](https://github.com/palkan/require-profiler).
+
+## Credits
+
+This gem is generated via [`newgem` template](https://github.com/palkan/newgem) by [@palkan](https://github.com/palkan).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+[speedscope]: https://www.speedscope.app/
+[require-hooks]: https://github.com/ruby-next/require-hooks

data/lib/require-profiler.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "require_profiler/version"
+require "require_profiler"

data/lib/require_profiler/printer/call_stack.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  module Printer
+    # CallStack formatter prints collapsed stacks (Brendan Gregg's format)
+    class CallStack < Base
+      def flush(node, parts: [])
+        path = node.path.sub(prefix_stripper, "")
+        self_parts = path.split("/")
+
+        parts += self_parts.size.times.map { self_parts.take(_1 + 1).join("/") }
+        # We only show self-time, so exclude children
+        val = ((node.time - node.children.sum(&:time)) * 1000).round(3)
+
+        output << "#{parts.join(";")} #{val}\n"
+
+        node.children.each { flush(_1, parts:) }
+      end
+    end
+  end
+end

data/lib/require_profiler/printer/json.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RequireProfiler
+  module Printer
+    # JSON formatter converts call tacks into Speedscope
+    # compatible JSON on finish.
+    #
+    # Can only be used with rewindable IO.
+    class JSON < CallStack
+      def finish
+        output.rewind
+        stacks = output.read
+        output.rewind
+
+        frames = []
+        frame_index = {}
+
+        samples = []
+        weights = []
+
+        stacks.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          sep = line.rindex(" ")
+          next unless sep
+
+          stack = line[0...sep]
+          weight = line[(sep + 1)..].to_f
+
+          sample = stack.split(";").map do |name|
+            frame_index[name] ||= begin
+              frames << {name: name}
+              frames.size - 1
+            end
+          end
+
+          samples << sample
+          weights << weight
+        end
+
+        total = weights.sum
+
+        profile = {
+          "$schema" => "https://www.speedscope.app/file-format-schema.json",
+          :shared => {frames: frames},
+          :profiles => [
+            {
+              type: "sampled",
+              unit: "milliseconds",
+              startValue: 0,
+              endValue: total,
+              samples:,
+              weights:
+            }
+          ]
+        }
+
+        output.write(::JSON.pretty_generate(profile))
+        super
+      end
+    end
+  end
+end

data/lib/require_profiler/printer/text.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  module Printer
+    class Text < Base
+      PAD = "  "
+
+      def flush(node, indent: 0)
+        path = node.path.sub(prefix_stripper, "")
+        output << "#{PAD * indent}#{path} — #{time_to_duration(node.time)}\n"
+        node.children.each { flush(_1, indent: indent + 1) }
+
+        output.flush
+      end
+
+      private
+
+      # Converts seconds to human-readable milliseconds
+      def time_to_duration(time) = "#{(time * 1000).round(3)}ms"
+    end
+  end
+end

data/lib/require_profiler/printer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  module Printer
+    class Base
+      private attr_reader :output
+      private attr_reader :prefix_stripper
+
+      def initialize(output)
+        @output = output
+
+        # Identify prefixes for the project and the gems
+        prefixes = [::Dir.pwd]
+        prefixes << ::Gem.dir if defined?(::Gem.dir)
+        prefixes << ::Bundler.bundle_path if defined?(::Bundler.bundle_path)
+
+        @prefix_stripper = %r{^(#{prefixes.join("|")})/}
+      end
+
+      def flush(node)
+        raise NotImplementedError
+      end
+
+      def finish
+        output.close if output.respond_to?(:close) && output != $stdout
+      end
+    end
+
+    autoload :Text, "require_profiler/printer/text"
+    autoload :CallStack, "require_profiler/printer/call_stack"
+    autoload :JSON, "require_profiler/printer/json"
+
+    class << self
+      def resolve(output, format)
+        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)
+        else
+          raise ArgumentError, "Unknown format specified: #{format}. Available formats: text, json, call_stack"
+        end
+      end
+    end
+  end
+end

data/lib/require_profiler/reporter.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  class Reporter
+    class Event < Struct.new(:type, :path, :time, keyword_init: true)
+    end
+
+    class Node < Struct.new(:path, :time, :children, keyword_init: true)
+      def initialize(...)
+        super
+        self.children ||= []
+      end
+    end
+
+    private attr_reader :stack, :totals, :printer, :processor, :queue
+
+    def initialize(printer:)
+      @stack = []
+      @totals = {count: 0, time: 0.0}
+      @printer = printer
+      @processor = nil
+      @queue = Queue.new
+
+      start_processor
+    end
+
+    def handle_event(event)
+      queue << event
+    end
+
+    def handle_event_sync(event)
+      if event.type == :start
+        node = Node.new(path: event.path, children: [])
+        stack.last&.children&.push(node)
+
+        stack << node
+      elsif event.type == :end
+        last = stack.pop
+        last.time = event.time
+
+        printer.flush(last) if stack.empty?
+
+        totals[:count] += 1
+        totals[:time] += event.time if stack.empty?
+      end
+    end
+
+    def finish
+      handle_event(Event.new(type: :stop))
+      processor.join
+
+      warn "Finished in the middle of requiring a file" unless stack.empty?
+
+      printer.finish
+      totals
+    end
+
+    private
+
+    def start_processor
+      @processor = Thread.new do
+        Thread.current.priority = -1
+
+        loop do
+          event = queue.pop
+
+          break if event.type == :stop
+
+          handle_event_sync(event)
+        end
+      end
+    end
+  end
+end

data/lib/require_profiler/version.rb

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

data/lib/require_profiler.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  autoload :Reporter, "require_profiler/reporter"
+  autoload :Printer, "require_profiler/printer"
+
+  class << self
+    attr_reader :reporter
+
+    def start(output: $stdout, format: nil, patterns: nil, exclude_patterns: nil)
+      raise ArgumentError, "There is already profiling in progress" if reporter
+
+      reporter = @reporter = Reporter.new(printer: Printer.resolve(output, format))
+
+      require "require-hooks/setup"
+
+      ::RequireHooks.around_load(patterns:, exclude_patterns:) do |path, &block|
+        start = Time.now
+
+        reporter.handle_event(Reporter::Event.new(type: :start, path:))
+
+        block.call
+      ensure
+        time = Time.now - start
+        reporter.handle_event(Reporter::Event.new(type: :end, path:, time:))
+      end
+    end
+
+    def stop
+      raise "No reporter defined. Are you sure you called RequireProfiler.start?" unless reporter
+
+      reporter.finish.tap do
+        @reporter = nil
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: require-profiler
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vladimir Dementyev
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: require-hooks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+description: 'Profile Ruby #require/#load/etc calls'
+email:
+- Vladimir Dementyev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/require-profiler.rb
+- lib/require_profiler.rb
+- lib/require_profiler/printer.rb
+- lib/require_profiler/printer/call_stack.rb
+- lib/require_profiler/printer/json.rb
+- lib/require_profiler/printer/text.rb
+- lib/require_profiler/reporter.rb
+- lib/require_profiler/version.rb
+homepage: https://github.com/palkan/require-profiler
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/palkan/require-profiler/issues
+  changelog_uri: https://github.com/palkan/require-profiler/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/palkan/require-profiler
+  homepage_uri: https://github.com/palkan/require-profiler
+  source_code_uri: https://github.com/palkan/require-profiler
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Profile Ruby #require/#load/etc calls'
+test_files: []