require-profiler 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 787aa181e1f018e66c9f8163837af8980a0549a23102361206451ca4c640675e
-  data.tar.gz: a7a0a01e40938642a7bd2b505ae18e47e42b3f00fa482c63151c5616d8f746d6
+  metadata.gz: d9031019da202ea4bf4ba530de358c6759bb8417de3f96047a138a9d262c0ff0
+  data.tar.gz: e51c7eb92cc7419bcdd396103a0565db26e9cf2fd97013577ffcc8b5b127a337
 SHA512:
-  metadata.gz: f99d748f75f3333f90979bfde8082591bb77e6b56590df2424dc566ff556798a50660d2c125d4b261c37235b0cdc95ff7cf228f146bd1e8f27d88af5498d90a3
-  data.tar.gz: b0b8aa77547e9852c91f699944877450aa03d125f4324b2efc5ea59854c293680215ee8bf272eda892a7c90c33ee5422bdecbeb3c6cf4530e2389a0aa1da8e05
+  metadata.gz: cc3d71a84a0faac6f801a9836dc0e0b3c3c6c3d694275f709f8a399229c8a1ee5cb8fe3b9ea4f1c311e04f93e0ffb3c28f3462ce6c582888e155da0a64b469d6
+  data.tar.gz: d16347ab1249f15e34f325f11f0505f17985c877bf2808b3e1727bff31c4369d95791032546f5f987034f1061ec95a774f1788646afc5f8c8b010374b26da1cc

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## master
 
+## 0.2.2 (2026-06-05)
+
+- Fixed YAML tracking when Pathname is used. ([@palkan][])
+
+## 0.2.1 (2026-05-26)
+
+- Add YAML tracking. ([@palkan][])
+
+- Add HTTP tracking via Sniffer. ([@palkan][])
+
 ## 0.2.0 (2026-05-25) 🔔
 
 - Add ability to run Stackprof for a particular file loading. ([@palkan][])

data/README.md

@@ -108,6 +108,10 @@ Now you can use Speedscope to dig deeper.
 
 **NOTE:** The `stackprof` gem must be present in your Gemfile for that.
 
+### YAML and HTTP support
+
+Require Profiler also captures HTTP requests and YAML file loading and add them to the profile, so you can find which Ruby files trigger the corresponding actions on load. NOTE: For HTTP requests tracking, you MUST add [sniffer][] gem to your Gemfile.
+
 ### Configuration
 
 `RequireProfiler.start` accepts the following keyword arguments:
@@ -189,3 +193,4 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 [speedscope]: https://www.speedscope.app/
 [require-hooks]: https://github.com/ruby-next/require-hooks
+[sniffer]: https://github.com/aderyabin/sniffer

data/lib/require_profiler/hyperdrive/skills/rails-boot-profiling/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: rails-boot-profiling
+description: Profile Rails application boot time to find slow requires. Use when the user asks why the app boots slowly, wants to profile boot time, or needs to optimize require/load performance.
+gem: require-profiler
+versions: ">= 0.2"
+---
+
+# Rails Boot Time Profiling
+
+Profile Rails application boot time using the require-profiler gem. This skill helps identify which `require`, `load`, YAML, and HTTP calls dominate startup time, and provides tools to drill deeper into slow files.
+
+## Prerequisites
+
+Before profiling, ensure these conditions are met:
+
+1. The `require-profiler` gem is in the Gemfile (at minimum in the development group).
+
+2. Eager loading must be enabled for the environment you are profiling. Check the environment config:
+
+```ruby
+# config/environments/development.rb (or the target environment)
+config.eager_load = true
+```
+
+If `eager_load` is `false`, the profile will miss most application code — only files loaded during boot are captured, and lazy-loaded files will not appear.
+
+3. Add `-W0` to the Ruby command to suppress warnings and keep output clean.
+
+## Step 1: Run a Full Boot Profile
+
+Run the base profiling command:
+
+```sh
+bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+```
+
+This loads `config/boot.rb` first (to set up Bundler and Bootsnap) and then profiles everything loaded by `config/environment.rb`.
+
+The output is an indented tree showing each required file with its load time (self + children) in milliseconds:
+
+```
+config/environment.rb — 4312.071ms
+  config/application.rb — 3672.445ms
+    railties (>= 0) — 1023.112ms
+      actionpack (>= 0) — 412.331ms
+        actionview (>= 0) — 198.442ms
+    app/models/user.rb — 87.203ms
+    app/models/order.rb — 142.891ms
+      app/models/concerns/auditable.rb — 12.004ms
+  config/initializers/stripe.rb — 523.117ms
+    stripe (>= 0) — 498.201ms
+```
+
+To get a quick count of how many files were loaded:
+
+```sh
+bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb | wc -l
+```
+
+## Step 2: Narrow the Scope
+
+### Filter by Threshold
+
+Exclude files that loaded faster than a given number of milliseconds (supports floats):
+
+```sh
+REQUIRE_PROFILE_THRESHOLD=100 bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+```
+
+This shows only files that took 100ms or more to load — useful for quickly spotting the biggest offenders.
+
+### Filter by Focus Pattern
+
+Show only files matching a pattern (uses `Regexp.new(...)` under the hood):
+
+```sh
+REQUIRE_PROFILE_FOCUS="stripe" bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+```
+
+The focus filter also keeps ancestor nodes in the tree, so you can see the full require chain leading to the matched files.
+
+Combine both for a precise view:
+
+```sh
+REQUIRE_PROFILE_THRESHOLD=50 REQUIRE_PROFILE_FOCUS="initializers" bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+```
+
+## Step 3: Check YAML and HTTP Activity During Boot
+
+By default, require-profiler tracks YAML file loads (`YAML.load_file`, etc.) and adds them to the profile tree. This helps find initializers or gems that parse large YAML configs at boot time.
+
+HTTP request tracking is also available but requires the [sniffer](https://github.com/aderyabin/sniffer) gem to be in the Gemfile. This surfaces any HTTP calls made during boot (e.g., config fetches from remote services, gem activation pings).
+
+To disable either:
+
+```sh
+# Disable YAML tracking
+REQUIRE_PROFILER_YAML=false bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+
+# Disable HTTP tracking
+REQUIRE_PROFILER_HTTP=false bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+
+# Disable all plugins (YAML + HTTP)
+REQUIRE_PROFILER_PLUGINS=false bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+```
+
+## Step 4: Deep-Dive with Stackprof
+
+When you identify a file that is unexpectedly slow to load, use Stackprof to profile what happens inside that file during `require`:
+
+```sh
+REQUIRE_PROFILE_STACKPROF=config/initializers/stripe.rb bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+```
+
+The `stackprof` gem must be in the Gemfile. This generates two files:
+
+- `config-initializers-stripe-stackprof.json` — JSON format, viewable in [Speedscope](https://www.speedscope.app/)
+- `config-initializers-stripe-stackprof.dump` — raw Stackprof data, analyzable with the `stackprof` CLI
+
+To analyze with the stackprof CLI:
+
+```sh
+bundle exec stackprof config-initializers-stripe-stackprof.dump
+bundle exec stackprof config-initializers-stripe-stackprof.dump --method 'ClassName#method_name'
+```
+
+To view in Speedscope, open https://www.speedscope.app/ and drag the `.json` file onto the page (nothing is uploaded — parsing is local).
+
+## Step 5: Export as JSON for Speedscope
+
+Generate a Speedscope-compatible JSON profile of the entire boot:
+
+```sh
+REQUIRE_PROFILE_PATH=tmp/require-profile.json bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+```
+
+This writes a JSON file conforming to the [Speedscope file format schema](https://www.speedscope.app/file-format-schema.json). Open it in Speedscope and use the **Left Heavy** view to find the most expensive require chains, and the **Sandwich** view to find files that appear repeatedly across different chains.
+
+If the Speedscope CLI is installed (`npm install -g speedscope`), open it directly:
+
+```sh
+npx speedscope tmp/require-profile.json
+```
+
+You can also use the `REQUIRE_PROFILE_FORMAT` env var to select the output format explicitly (`text`, `json`, or `call_stack`). When the output path ends in `.json`, the JSON format is selected automatically.
+
+## Collapsed Call Stack Format
+
+For flame graph generation with external tools (e.g., `flamegraph.pl`, `inferno`), use the collapsed call stack format:
+
+```sh
+REQUIRE_PROFILE_FORMAT=call_stack REQUIRE_PROFILE_PATH=tmp/require-profile.txt bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
+```
+
+This emits one line per stack in Brendan Gregg's collapsed format with per-frame self time in milliseconds.
+
+## Environment Variable Reference
+
+| Variable | Purpose | Example |
+|---|---|---|
+| `REQUIRE_PROFILE_THRESHOLD` | Minimum load time in ms to include (float) | `100`, `50.5` |
+| `REQUIRE_PROFILE_FOCUS` | Regexp pattern to filter files | `"stripe"`, `"initializers"` |
+| `REQUIRE_PROFILE_PATH` | Output file path (enables file output) | `tmp/require-profile.json` |
+| `REQUIRE_PROFILE_FORMAT` | Output format: `text`, `json`, `call_stack` | `json` |
+| `REQUIRE_PROFILE_STACKPROF` | File path to deep-profile with Stackprof | `config/initializers/stripe.rb` |
+| `REQUIRE_PROFILER_YAML` | Disable YAML tracking when set to `false` | `false` |
+| `REQUIRE_PROFILER_HTTP` | Disable HTTP tracking when set to `false` | `false` |
+| `REQUIRE_PROFILER_PLUGINS` | Disable all plugins when set to `false` | `false` |
+
+## Recommended Agent Workflow
+
+Follow this sequence when a user asks about slow boot time:
+
+1. **Get a baseline.** Run the full profile command and note the total boot time (the top-level entry's duration) and total file count (`| wc -l`).
+
+2. **Find the top offenders.** Re-run with `REQUIRE_PROFILE_THRESHOLD=100` (or adjust based on total time) to surface only slow files. Report the top 5-10 slowest entries to the user.
+
+3. **Investigate specific areas.** If the user suspects a particular gem or area, use `REQUIRE_PROFILE_FOCUS` to zoom in. Otherwise, focus on the slowest entries from step 2.
+
+4. **Check for boot-time side effects.** Look at YAML and HTTP entries in the profile. HTTP calls during boot are almost always worth investigating — they add latency and can fail. YAML loads of large files can also be significant.
+
+5. **Deep-dive when needed.** For files that are unexpectedly slow (the load time seems too high for what the file does), use `REQUIRE_PROFILE_STACKPROF` to generate a Stackprof profile and identify what's happening inside that file.
+
+6. **Generate a JSON profile for handoff.** If the user wants to explore the data themselves, or if the profile is too large to analyze in text, export to JSON with `REQUIRE_PROFILE_PATH=tmp/require-profile.json` and point them to Speedscope.
+
+7. **Suggest actionable improvements** based on findings:
+   - Move heavy gem requires behind lazy loading or autoload
+   - Defer initializer work to `after_initialize` or `to_prepare` callbacks
+   - Replace boot-time HTTP calls with cached configs or async fetches
+   - Split large YAML files or cache parsed results
+   - Consider using `bootsnap` if not already present

data/lib/require_profiler/plugins/http_plugin.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  module Plugins
+    # Track HTTP calls using Sniffer and add the to the require profile
+    class HTTPPlugin < Base
+      def activate!
+        begin
+          require "sniffer"
+        rescue LoadError
+          return
+        end
+
+        Sniffer.config.logger = Logger.new(IO::NULL)
+
+        Sniffer.config.middleware do |chain|
+          chain.add HTTPPlugin, reporter
+        end
+
+        Sniffer::DataItem::Request.include(Module.new do
+          def require_path
+            @url ||= "#{method.to_s.upcase}:#{(port == 443) ? "https" : "http"}://#{host}#{query}"
+          end
+        end)
+
+        Sniffer.enable!
+      end
+
+      # Sniffer hook interface
+      def request(data_item)
+        reporter.handle_event(Reporter::Event.new(type: :start, kind: :http, path: data_item.request.require_path))
+        yield
+      end
+
+      def response(data_item)
+        yield
+        time = data_item.response.timing
+        reporter.handle_event(Reporter::Event.new(type: :end, path: data_item.request.require_path, time:))
+      end
+    end
+  end
+end

data/lib/require_profiler/plugins/yaml_plugin.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  module Plugins
+    # Track loading YAML files
+    class YAMLPlugin < Base
+      module Patch
+        def load_file(path, ...)
+          YAMLPlugin.track(path.to_s) { super }
+        end
+
+        def unsafe_load_file(path, ...)
+          YAMLPlugin.track(path.to_s) { super }
+        end
+
+        def safe_load_file(path, ...)
+          YAMLPlugin.track(path.to_s) { super }
+        end
+      end
+
+      class << self
+        attr_accessor :reporter
+
+        def track(path)
+          reporter.handle_event(Reporter::Event.new(type: :start, kind: :yml, path:))
+          start = Time.now
+          yield
+        ensure
+          time = Time.now - start
+          reporter.handle_event(Reporter::Event.new(type: :end, path:, time:))
+        end
+      end
+
+      def activate!
+        require "yaml"
+
+        YAMLPlugin.reporter = reporter
+        ::YAML.singleton_class.prepend(Patch)
+      end
+    end
+  end
+end

data/lib/require_profiler/plugins.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RequireProfiler
+  module Plugins
+    class << self
+      def register_reporter(reporter)
+        HTTPPlugin.new(reporter).activate! unless ENV["REQUIRE_PROFILER_HTTP"] == "false"
+        YAMLPlugin.new(reporter).activate! unless ENV["REQUIRE_PROFILER_YAML"] == "false"
+      end
+    end
+
+    class Base
+      attr_reader :reporter
+
+      def initialize(reporter)
+        @reporter = reporter
+      end
+    end
+
+    autoload :HTTPPlugin, "require_profiler/plugins/http_plugin"
+    autoload :YAMLPlugin, "require_profiler/plugins/yaml_plugin"
+  end
+end

data/lib/require_profiler/printer/call_stack.rb

@@ -8,7 +8,7 @@ module RequireProfiler
         return unless flush?(node)
 
         path = node.path.sub(prefix_stripper, "")
-        self_parts = path.split("/")
+        self_parts = (node.kind == :path) ? path.split("/") : [path]
 
         parts += self_parts.size.times.map { self_parts.take(_1 + 1).join("/") }
         # We only show self-time, so exclude children

data/lib/require_profiler/reporter.rb

@@ -2,14 +2,15 @@
 
 module RequireProfiler
   class Reporter
-    class Event < Struct.new(:type, :path, :time, keyword_init: true)
+    class Event < Struct.new(:type, :path, :time, :kind, keyword_init: true)
     end
 
-    class Node < Struct.new(:path, :time, :parent, :children, :focused, keyword_init: true)
+    class Node < Struct.new(:path, :time, :parent, :children, :kind, :focused, keyword_init: true)
       def initialize(...)
         super
         self.children ||= []
         self.focused = false
+        self.kind ||= :path
       end
 
       def focused!
@@ -37,7 +38,7 @@ module RequireProfiler
 
     def handle_event_sync(event)
       if event.type == :start
-        node = Node.new(path: event.path, children: [])
+        node = Node.new(path: event.path, children: [], kind: event.kind)
         parent = stack.last
 
         if parent

data/lib/require_profiler/version.rb

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

data/lib/require_profiler.rb

@@ -3,6 +3,7 @@
 module RequireProfiler
   autoload :Reporter, "require_profiler/reporter"
   autoload :Printer, "require_profiler/printer"
+  autoload :Plugins, "require_profiler/plugins"
 
   # Autoload doesn't work here, because we call it from the hooks for the first time
   require "require_profiler/ruby_profiling"
@@ -38,6 +39,8 @@ module RequireProfiler
         time = Time.now - start
         reporter.handle_event(Reporter::Event.new(type: :end, path:, time:))
       end
+
+      Plugins.register_reporter(reporter) unless ENV["REQUIRE_PROFILER_PLUGINS"] == "false"
     end
 
     def stop

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: require-profiler
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Vladimir Dementyev
@@ -37,6 +37,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +93,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: sniffer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
 description: 'Profile Ruby #require/#load/etc calls'
 email:
 - Vladimir Dementyev
@@ -78,6 +134,10 @@ files:
 - lib/equire-prof.rb
 - lib/require-profiler.rb
 - lib/require_profiler.rb
+- lib/require_profiler/hyperdrive/skills/rails-boot-profiling/SKILL.md
+- lib/require_profiler/plugins.rb
+- lib/require_profiler/plugins/http_plugin.rb
+- lib/require_profiler/plugins/yaml_plugin.rb
 - lib/require_profiler/printer.rb
 - lib/require_profiler/printer/call_stack.rb
 - lib/require_profiler/printer/json.rb
@@ -94,6 +154,8 @@ metadata:
   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
+  hyperdrive_targets: railties
+  hyperdrive_artifacts: skill
 rdoc_options: []
 require_paths:
 - lib