require-profiler 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +14 -0
- data/README.md +11 -2
- data/lib/require_profiler/patcher.rb +36 -0
- data/lib/require_profiler/plugins/http_plugin.rb +1 -1
- data/lib/require_profiler/plugins/rails_plugin.rb +66 -0
- data/lib/require_profiler/plugins/yaml_plugin.rb +3 -3
- data/lib/require_profiler/plugins.rb +2 -0
- data/lib/require_profiler/printer/call_stack.rb +23 -3
- data/lib/require_profiler/printer/text.rb +1 -1
- data/lib/require_profiler/printer.rb +5 -1
- data/lib/require_profiler/version.rb +1 -1
- data/lib/require_profiler.rb +1 -0
- data/skills/rails-boot-profiling/SKILL.md +237 -0
- metadata +22 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9f7525e2f089705293ecb70a35d28837fb45c144b9c58861c9904d8b58a9e49a
|
|
4
|
+
data.tar.gz: 8a5e2acb8665b0bb7d665d91d0598d16c61d7488f7d40bed23cc1afe03559e7a
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: ef22d5d6c1a8d98bc7418802be6b95f9a84e82336e4f1de1681cddfba631ca187c504ccf343d2ea25832b46ca1a6c00bd411996bb8c77315a6f0311a4c5895dd
|
|
7
|
+
data.tar.gz: ae0f1a579693c2242f78eab1f4898e94ed54701ff8d3cc4d080b534791f9043206da1d89ef2da58cf5dcd67fc27404bcf0e2b0aae15d14e67d9f2a3a8c3a0812
|
data/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
## master
|
|
4
4
|
|
|
5
|
+
## 0.3.0 (2026-07-23)
|
|
6
|
+
|
|
7
|
+
- Add Rails initialization tracking: railtie initializers, `to_prepare` callbacks, and lazy load hooks. ([@ardecvz][])
|
|
8
|
+
|
|
9
|
+
- Prefix HTTP nodes with `http:`. ([@ardecvz][])
|
|
10
|
+
|
|
11
|
+
## 0.2.3 (2026-06-05)
|
|
12
|
+
|
|
13
|
+
- Add SKILL.md for rails-hyperdrive. ([@palkan][])
|
|
14
|
+
|
|
15
|
+
## 0.2.2 (2026-06-05)
|
|
16
|
+
|
|
17
|
+
- Fixed YAML tracking when Pathname is used. ([@palkan][])
|
|
18
|
+
|
|
5
19
|
## 0.2.1 (2026-05-26)
|
|
6
20
|
|
|
7
21
|
- Add YAML tracking. ([@palkan][])
|
data/README.md
CHANGED
|
@@ -7,8 +7,9 @@ Require Profiler is a tool for profiling Ruby's code loading—`Kernel#require`,
|
|
|
7
7
|
|
|
8
8
|
It's built on top of [Require Hooks][require-hooks], so it works anywhere Require Hooks does (MRI/JRuby/TruffleRuby).
|
|
9
9
|
|
|
10
|
-
<
|
|
11
|
-
|
|
10
|
+
<br/>
|
|
11
|
+
|
|
12
|
+
<img src="https://cdn.evilmartians.com/badges/logo-no-label.svg" alt="Evil Martians logo" width="22" height="16" /> <b>Require Profiler</b> is built by <b><a href="https://evilmartians.com/">Evil Martians</a></b>, an American design and engineering consultancy for <b>developer tools, AI, and cybersecurity startups</b>.
|
|
12
13
|
|
|
13
14
|
## Installation
|
|
14
15
|
|
|
@@ -112,6 +113,14 @@ Now you can use Speedscope to dig deeper.
|
|
|
112
113
|
|
|
113
114
|
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.
|
|
114
115
|
|
|
116
|
+
Disable with `REQUIRE_PROFILER_YAML=false` or `REQUIRE_PROFILER_HTTP=false`.
|
|
117
|
+
|
|
118
|
+
### Rails integration
|
|
119
|
+
|
|
120
|
+
When Rails is loaded, Require Profiler automatically captures its initialization - railtie initializers, `to_prepare` callbacks, and lazy load hooks - and adds them to the profile as `initializer:`, `to_prepare:`, and `load_hook:` nodes, so you can find the slow-running blocks, which are usually invisible when profiling code loading alone.
|
|
121
|
+
|
|
122
|
+
Disable with `REQUIRE_PROFILER_RAILS=false` (or set a threshold if the extra nodes add too much noise).
|
|
123
|
+
|
|
115
124
|
### Configuration
|
|
116
125
|
|
|
117
126
|
`RequireProfiler.start` accepts the following keyword arguments:
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module RequireProfiler
|
|
4
|
+
# Use TracePoint to run a callback when a particular class is defined
|
|
5
|
+
module Patcher
|
|
6
|
+
class << self
|
|
7
|
+
def on_load(name, &callback)
|
|
8
|
+
return callback.call if Object.const_defined?(name)
|
|
9
|
+
|
|
10
|
+
callbacks[name] = callback
|
|
11
|
+
|
|
12
|
+
tracer.enable
|
|
13
|
+
end
|
|
14
|
+
|
|
15
|
+
private
|
|
16
|
+
|
|
17
|
+
def callbacks = @callbacks ||= {}
|
|
18
|
+
|
|
19
|
+
def tracer = @tracer ||= TracePoint.new(:end, &method(:on_class))
|
|
20
|
+
|
|
21
|
+
def name_method = @name_method ||= Module.instance_method(:name)
|
|
22
|
+
|
|
23
|
+
def on_class(event)
|
|
24
|
+
return if event.self.singleton_class?
|
|
25
|
+
|
|
26
|
+
class_name = name_method.bind_call(event.self)
|
|
27
|
+
return unless callbacks[class_name]
|
|
28
|
+
|
|
29
|
+
callback = callbacks.delete(class_name)
|
|
30
|
+
tracer.disable if callbacks.empty?
|
|
31
|
+
|
|
32
|
+
callback.call
|
|
33
|
+
end
|
|
34
|
+
end
|
|
35
|
+
end
|
|
36
|
+
end
|
|
@@ -19,7 +19,7 @@ module RequireProfiler
|
|
|
19
19
|
|
|
20
20
|
Sniffer::DataItem::Request.include(Module.new do
|
|
21
21
|
def require_path
|
|
22
|
-
@url ||= "
|
|
22
|
+
@url ||= "http:#{method.to_s.upcase}:#{(port == 443) ? "https" : "http"}://#{host}#{query}"
|
|
23
23
|
end
|
|
24
24
|
end)
|
|
25
25
|
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module RequireProfiler
|
|
4
|
+
module Plugins
|
|
5
|
+
# Track Rails initialization: railtie initializers, to_prepare callbacks, and load hooks
|
|
6
|
+
class RailsPlugin < Base
|
|
7
|
+
module InitializerPatch
|
|
8
|
+
def run(...)
|
|
9
|
+
RailsPlugin.track(:initializer, name, block) { super }
|
|
10
|
+
end
|
|
11
|
+
end
|
|
12
|
+
|
|
13
|
+
module ToPreparePatch
|
|
14
|
+
def to_prepare(*args, &block)
|
|
15
|
+
return super unless block
|
|
16
|
+
|
|
17
|
+
super do |*prepare_args|
|
|
18
|
+
RailsPlugin.track(:to_prepare, nil, block) do
|
|
19
|
+
instance_exec(*prepare_args, &block)
|
|
20
|
+
end
|
|
21
|
+
end
|
|
22
|
+
end
|
|
23
|
+
end
|
|
24
|
+
|
|
25
|
+
module LoadHookPatch
|
|
26
|
+
private
|
|
27
|
+
|
|
28
|
+
def execute_hook(name, base, options, block)
|
|
29
|
+
RailsPlugin.track(:load_hook, name, block) { super }
|
|
30
|
+
end
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
class << self
|
|
34
|
+
attr_accessor :reporter
|
|
35
|
+
|
|
36
|
+
def track(kind, name, block)
|
|
37
|
+
path = label(kind, name, block)
|
|
38
|
+
reporter.handle_event(Reporter::Event.new(type: :start, kind: :rails, path:))
|
|
39
|
+
start = Time.now
|
|
40
|
+
yield
|
|
41
|
+
ensure
|
|
42
|
+
time = Time.now - start
|
|
43
|
+
reporter.handle_event(Reporter::Event.new(type: :end, path:, time:))
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
def label(kind, name, block)
|
|
47
|
+
["rails:#{kind}", name, block&.source_location&.join(":")].compact.join(":")
|
|
48
|
+
end
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
def activate!
|
|
52
|
+
RailsPlugin.reporter = reporter
|
|
53
|
+
|
|
54
|
+
Patcher.on_load("Rails::Initializable::Initializer") do
|
|
55
|
+
::Rails::Initializable::Initializer.prepend(InitializerPatch)
|
|
56
|
+
end
|
|
57
|
+
Patcher.on_load("ActiveSupport::Reloader") do
|
|
58
|
+
::ActiveSupport::Reloader.singleton_class.prepend(ToPreparePatch)
|
|
59
|
+
end
|
|
60
|
+
Patcher.on_load("ActiveSupport::LazyLoadHooks") do
|
|
61
|
+
::ActiveSupport.singleton_class.prepend(LoadHookPatch)
|
|
62
|
+
end
|
|
63
|
+
end
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
end
|
|
@@ -6,15 +6,15 @@ module RequireProfiler
|
|
|
6
6
|
class YAMLPlugin < Base
|
|
7
7
|
module Patch
|
|
8
8
|
def load_file(path, ...)
|
|
9
|
-
YAMLPlugin.track(path) { super }
|
|
9
|
+
YAMLPlugin.track(path.to_s) { super }
|
|
10
10
|
end
|
|
11
11
|
|
|
12
12
|
def unsafe_load_file(path, ...)
|
|
13
|
-
YAMLPlugin.track(path) { super }
|
|
13
|
+
YAMLPlugin.track(path.to_s) { super }
|
|
14
14
|
end
|
|
15
15
|
|
|
16
16
|
def safe_load_file(path, ...)
|
|
17
|
-
YAMLPlugin.track(path) { super }
|
|
17
|
+
YAMLPlugin.track(path.to_s) { super }
|
|
18
18
|
end
|
|
19
19
|
end
|
|
20
20
|
|
|
@@ -6,6 +6,7 @@ module RequireProfiler
|
|
|
6
6
|
def register_reporter(reporter)
|
|
7
7
|
HTTPPlugin.new(reporter).activate! unless ENV["REQUIRE_PROFILER_HTTP"] == "false"
|
|
8
8
|
YAMLPlugin.new(reporter).activate! unless ENV["REQUIRE_PROFILER_YAML"] == "false"
|
|
9
|
+
RailsPlugin.new(reporter).activate! unless ENV["REQUIRE_PROFILER_RAILS"] == "false"
|
|
9
10
|
end
|
|
10
11
|
end
|
|
11
12
|
|
|
@@ -19,5 +20,6 @@ module RequireProfiler
|
|
|
19
20
|
|
|
20
21
|
autoload :HTTPPlugin, "require_profiler/plugins/http_plugin"
|
|
21
22
|
autoload :YAMLPlugin, "require_profiler/plugins/yaml_plugin"
|
|
23
|
+
autoload :RailsPlugin, "require_profiler/plugins/rails_plugin"
|
|
22
24
|
end
|
|
23
25
|
end
|
|
@@ -4,13 +4,22 @@ module RequireProfiler
|
|
|
4
4
|
module Printer
|
|
5
5
|
# CallStack formatter prints collapsed stacks (Brendan Gregg's format)
|
|
6
6
|
class CallStack < Base
|
|
7
|
+
# Rails labels are "rails:#{type}:#{detail}", e.g. "rails:initializer:name:file:line"
|
|
8
|
+
RAILS_LABEL_PARTS = 3
|
|
9
|
+
RAILS_TYPE_INDEX = 1
|
|
10
|
+
|
|
7
11
|
def flush(node, parts: [])
|
|
8
12
|
return unless flush?(node)
|
|
9
13
|
|
|
10
|
-
path = node.path
|
|
11
|
-
self_parts =
|
|
14
|
+
path = strip_prefix(node.path)
|
|
15
|
+
self_parts =
|
|
16
|
+
case node.kind
|
|
17
|
+
when :rails then rails_frames(path)
|
|
18
|
+
when :path then path_frames(path)
|
|
19
|
+
else [path]
|
|
20
|
+
end
|
|
12
21
|
|
|
13
|
-
parts += self_parts
|
|
22
|
+
parts += self_parts
|
|
14
23
|
# We only show self-time, so exclude children
|
|
15
24
|
val = ((node.time - node.children.sum(&:time)) * 1000).round(3)
|
|
16
25
|
|
|
@@ -18,6 +27,17 @@ module RequireProfiler
|
|
|
18
27
|
|
|
19
28
|
node.children.each { flush(_1, parts:) }
|
|
20
29
|
end
|
|
30
|
+
|
|
31
|
+
private
|
|
32
|
+
|
|
33
|
+
def rails_frames(path)
|
|
34
|
+
["rails:#{path.split(":", RAILS_LABEL_PARTS)[RAILS_TYPE_INDEX]}", path]
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
def path_frames(path)
|
|
38
|
+
segments = path.split("/")
|
|
39
|
+
segments.size.times.map { segments.take(_1 + 1).join("/") }
|
|
40
|
+
end
|
|
21
41
|
end
|
|
22
42
|
end
|
|
23
43
|
end
|
|
@@ -8,7 +8,7 @@ module RequireProfiler
|
|
|
8
8
|
def flush(node, indent: 0)
|
|
9
9
|
return unless flush?(node)
|
|
10
10
|
|
|
11
|
-
path = node.path
|
|
11
|
+
path = strip_prefix(node.path)
|
|
12
12
|
output << "#{PAD * indent}#{path} — #{time_to_duration(node.time)}\n"
|
|
13
13
|
node.children.each { flush(_1, indent: indent + 1) }
|
|
14
14
|
|
|
@@ -16,7 +16,7 @@ module RequireProfiler
|
|
|
16
16
|
prefixes << ::Gem.dir if defined?(::Gem.dir)
|
|
17
17
|
prefixes << ::Bundler.bundle_path if defined?(::Bundler.bundle_path)
|
|
18
18
|
|
|
19
|
-
@prefix_stripper = %r{
|
|
19
|
+
@prefix_stripper = %r{(^|:)(#{prefixes.join("|")})/}
|
|
20
20
|
end
|
|
21
21
|
|
|
22
22
|
def flush(node)
|
|
@@ -29,6 +29,10 @@ module RequireProfiler
|
|
|
29
29
|
|
|
30
30
|
private
|
|
31
31
|
|
|
32
|
+
def strip_prefix(path)
|
|
33
|
+
path.sub(prefix_stripper, '\1')
|
|
34
|
+
end
|
|
35
|
+
|
|
32
36
|
def flush?(node)
|
|
33
37
|
return false unless (node.time * 1000) >= threshold
|
|
34
38
|
|
data/lib/require_profiler.rb
CHANGED
|
@@ -4,6 +4,7 @@ module RequireProfiler
|
|
|
4
4
|
autoload :Reporter, "require_profiler/reporter"
|
|
5
5
|
autoload :Printer, "require_profiler/printer"
|
|
6
6
|
autoload :Plugins, "require_profiler/plugins"
|
|
7
|
+
autoload :Patcher, "require_profiler/patcher"
|
|
7
8
|
|
|
8
9
|
# Autoload doesn't work here, because we call it from the hooks for the first time
|
|
9
10
|
require "require_profiler/ruby_profiling"
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: rails-boot-profiling
|
|
3
|
+
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.
|
|
4
|
+
gem: require-profiler
|
|
5
|
+
versions: ">= 0.2"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Rails Boot Time Profiling
|
|
9
|
+
|
|
10
|
+
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.
|
|
11
|
+
|
|
12
|
+
## Prerequisites
|
|
13
|
+
|
|
14
|
+
Before profiling, ensure these conditions are met:
|
|
15
|
+
|
|
16
|
+
1. The `require-profiler` gem is in the Gemfile (at minimum in the development group).
|
|
17
|
+
|
|
18
|
+
2. Eager loading must be enabled for the environment you are profiling. Check the environment config:
|
|
19
|
+
|
|
20
|
+
```ruby
|
|
21
|
+
# config/environments/development.rb (or the target environment)
|
|
22
|
+
config.eager_load = true
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
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.
|
|
26
|
+
|
|
27
|
+
3. Add `-W0` to the Ruby command to suppress warnings and keep output clean.
|
|
28
|
+
|
|
29
|
+
## Step 1: Run a Full Boot Profile
|
|
30
|
+
|
|
31
|
+
Run the base profiling command:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
This loads `config/boot.rb` first (to set up Bundler and Bootsnap) and then profiles everything loaded by `config/environment.rb`.
|
|
38
|
+
|
|
39
|
+
The output is an indented tree showing each required file with its load time (self + children) in milliseconds:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
config/environment.rb — 4312.071ms
|
|
43
|
+
config/application.rb — 3672.445ms
|
|
44
|
+
railties (>= 0) — 1023.112ms
|
|
45
|
+
actionpack (>= 0) — 412.331ms
|
|
46
|
+
actionview (>= 0) — 198.442ms
|
|
47
|
+
app/models/user.rb — 87.203ms
|
|
48
|
+
app/models/order.rb — 142.891ms
|
|
49
|
+
app/models/concerns/auditable.rb — 12.004ms
|
|
50
|
+
config/initializers/stripe.rb — 523.117ms
|
|
51
|
+
stripe (>= 0) — 498.201ms
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
To get a quick count of how many files were loaded:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb | wc -l
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Step 2: Narrow the Scope
|
|
61
|
+
|
|
62
|
+
### Filter by Threshold
|
|
63
|
+
|
|
64
|
+
Exclude files that loaded faster than a given number of milliseconds (supports floats):
|
|
65
|
+
|
|
66
|
+
```sh
|
|
67
|
+
REQUIRE_PROFILE_THRESHOLD=100 bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
This shows only files that took 100ms or more to load — useful for quickly spotting the biggest offenders.
|
|
71
|
+
|
|
72
|
+
### Filter by Focus Pattern
|
|
73
|
+
|
|
74
|
+
Show only files matching a pattern (uses `Regexp.new(...)` under the hood):
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
REQUIRE_PROFILE_FOCUS="stripe" bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The focus filter also keeps ancestor nodes in the tree, so you can see the full require chain leading to the matched files.
|
|
81
|
+
|
|
82
|
+
Combine both for a precise view:
|
|
83
|
+
|
|
84
|
+
```sh
|
|
85
|
+
REQUIRE_PROFILE_THRESHOLD=50 REQUIRE_PROFILE_FOCUS="initializers" bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Step 3: Check YAML and HTTP Activity During Boot
|
|
89
|
+
|
|
90
|
+
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.
|
|
91
|
+
|
|
92
|
+
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).
|
|
93
|
+
|
|
94
|
+
To disable either:
|
|
95
|
+
|
|
96
|
+
```sh
|
|
97
|
+
# Disable YAML tracking
|
|
98
|
+
REQUIRE_PROFILER_YAML=false bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
99
|
+
|
|
100
|
+
# Disable HTTP tracking
|
|
101
|
+
REQUIRE_PROFILER_HTTP=false bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
102
|
+
|
|
103
|
+
# Disable all plugins (YAML + HTTP)
|
|
104
|
+
REQUIRE_PROFILER_PLUGINS=false bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Step 4: Deep-Dive with Stackprof
|
|
108
|
+
|
|
109
|
+
When you identify a file that is unexpectedly slow to load, use Stackprof to profile what happens inside that file during `require`:
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
REQUIRE_PROFILE_STACKPROF=config/initializers/stripe.rb bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The `stackprof` gem must be in the Gemfile. This generates two files:
|
|
116
|
+
|
|
117
|
+
- `config-initializers-stripe-stackprof.json` — JSON format, viewable in [Speedscope](https://www.speedscope.app/)
|
|
118
|
+
- `config-initializers-stripe-stackprof.dump` — raw Stackprof data, analyzable with the `stackprof` CLI
|
|
119
|
+
|
|
120
|
+
To analyze with the stackprof CLI:
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
bundle exec stackprof config-initializers-stripe-stackprof.dump
|
|
124
|
+
bundle exec stackprof config-initializers-stripe-stackprof.dump --method 'ClassName#method_name'
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
To view in Speedscope, open https://www.speedscope.app/ and drag the `.json` file onto the page (nothing is uploaded — parsing is local).
|
|
128
|
+
|
|
129
|
+
## Step 5: Export as JSON for Speedscope
|
|
130
|
+
|
|
131
|
+
Generate a Speedscope-compatible JSON profile of the entire boot:
|
|
132
|
+
|
|
133
|
+
```sh
|
|
134
|
+
REQUIRE_PROFILE_PATH=tmp/require-profile.json bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
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.
|
|
138
|
+
|
|
139
|
+
If the Speedscope CLI is installed (`npm install -g speedscope`), open it directly:
|
|
140
|
+
|
|
141
|
+
```sh
|
|
142
|
+
npx speedscope tmp/require-profile.json
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
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.
|
|
146
|
+
|
|
147
|
+
## Collapsed Call Stack Format
|
|
148
|
+
|
|
149
|
+
For flame graph generation with external tools (e.g., `flamegraph.pl`, `inferno`), use the collapsed call stack format:
|
|
150
|
+
|
|
151
|
+
```sh
|
|
152
|
+
REQUIRE_PROFILE_FORMAT=call_stack REQUIRE_PROFILE_PATH=tmp/require-profile.txt bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
This emits one line per stack in Brendan Gregg's collapsed format with per-frame self time in milliseconds.
|
|
156
|
+
|
|
157
|
+
## Environment Variable Reference
|
|
158
|
+
|
|
159
|
+
| Variable | Purpose | Example |
|
|
160
|
+
|---|---|---|
|
|
161
|
+
| `REQUIRE_PROFILE_THRESHOLD` | Minimum load time in ms to include (float) | `100`, `50.5` |
|
|
162
|
+
| `REQUIRE_PROFILE_FOCUS` | Regexp pattern to filter files | `"stripe"`, `"initializers"` |
|
|
163
|
+
| `REQUIRE_PROFILE_PATH` | Output file path (enables file output) | `tmp/require-profile.json` |
|
|
164
|
+
| `REQUIRE_PROFILE_FORMAT` | Output format: `text`, `json`, `call_stack` | `json` |
|
|
165
|
+
| `REQUIRE_PROFILE_STACKPROF` | File path to deep-profile with Stackprof | `config/initializers/stripe.rb` |
|
|
166
|
+
| `REQUIRE_PROFILER_YAML` | Disable YAML tracking when set to `false` | `false` |
|
|
167
|
+
| `REQUIRE_PROFILER_HTTP` | Disable HTTP tracking when set to `false` | `false` |
|
|
168
|
+
| `REQUIRE_PROFILER_PLUGINS` | Disable all plugins when set to `false` | `false` |
|
|
169
|
+
|
|
170
|
+
## Important: Use the Profiler's Built-in Filtering
|
|
171
|
+
|
|
172
|
+
**Prefer profiler's built-in filtering and searching capabilities over `grep`, `tail`, `head`, `awk`, or `sed` to filter or search results.**:
|
|
173
|
+
|
|
174
|
+
- To find slow files → use `REQUIRE_PROFILE_THRESHOLD`, not `grep` for timing patterns
|
|
175
|
+
- To investigate a specific gem or file → use `REQUIRE_PROFILE_FOCUS`, not `grep` for the name
|
|
176
|
+
- To reduce output size → use `REQUIRE_PROFILE_THRESHOLD` + `REQUIRE_PROFILE_FOCUS`, not `tail -N | head -M`
|
|
177
|
+
|
|
178
|
+
Shell-based filtering breaks the indented tree structure (you lose parent-child relationships), misses context, and requires re-running the full profile each time you change the filter. The built-in env vars preserve the tree, show ancestor chains, and handle edge cases the profiler already knows about.
|
|
179
|
+
|
|
180
|
+
The only acceptable uses of piping are:
|
|
181
|
+
- `| wc -l` to count total loaded files in step 1
|
|
182
|
+
- Piping into a file when `REQUIRE_PROFILE_PATH` is not available
|
|
183
|
+
|
|
184
|
+
## Recommended Agent Workflow
|
|
185
|
+
|
|
186
|
+
Follow this sequence when a user asks about slow boot time:
|
|
187
|
+
|
|
188
|
+
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`).
|
|
189
|
+
|
|
190
|
+
```sh
|
|
191
|
+
bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
2. **Find the top offenders.** Re-run with `REQUIRE_PROFILE_THRESHOLD` to surface only slow files. Start with a threshold that shows roughly 10-20 entries (e.g., if total boot is ~4s, try 100ms; if ~1s, try 30ms). Report the top slowest entries to the user.
|
|
195
|
+
|
|
196
|
+
```sh
|
|
197
|
+
REQUIRE_PROFILE_THRESHOLD=100 bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
3. **Investigate specific areas.** Use `REQUIRE_PROFILE_FOCUS` to zoom into a gem, initializer, or file. The focus pattern is a regexp — use it to match file paths, gem names, or directory patterns. Combine with `REQUIRE_PROFILE_THRESHOLD` for precision.
|
|
201
|
+
|
|
202
|
+
```sh
|
|
203
|
+
# Investigate a specific gem
|
|
204
|
+
REQUIRE_PROFILE_FOCUS="stripe" bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
205
|
+
|
|
206
|
+
# Investigate all initializers that took > 50ms
|
|
207
|
+
REQUIRE_PROFILE_THRESHOLD=50 REQUIRE_PROFILE_FOCUS="initializers" bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
4. **Check for boot-time side effects.** YAML and HTTP entries appear in the profile tree by default. HTTP calls during boot are almost always worth investigating — they add latency and can fail. Use `REQUIRE_PROFILE_FOCUS` to find them:
|
|
211
|
+
|
|
212
|
+
```sh
|
|
213
|
+
# Find YAML loading
|
|
214
|
+
REQUIRE_PROFILE_FOCUS="\.yml" bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
215
|
+
|
|
216
|
+
# Find HTTP calls during boot
|
|
217
|
+
REQUIRE_PROFILE_FOCUS="(GET|POST|PATCH|DELETE):" bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
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.
|
|
221
|
+
|
|
222
|
+
```sh
|
|
223
|
+
REQUIRE_PROFILE_STACKPROF=config/initializers/stripe.rb bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
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 and point them to Speedscope.
|
|
227
|
+
|
|
228
|
+
```sh
|
|
229
|
+
REQUIRE_PROFILE_PATH=tmp/require-profile.json bundle exec ruby -W0 -r./config/boot -require-prof config/environment.rb
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
7. **Suggest actionable improvements** based on findings:
|
|
233
|
+
- Move heavy gem requires behind lazy loading or autoload
|
|
234
|
+
- Defer initializer work to `after_initialize` or `to_prepare` callbacks
|
|
235
|
+
- Replace boot-time HTTP calls with cached configs or async fetches
|
|
236
|
+
- Split large YAML files or cache parsed results
|
|
237
|
+
- Consider using `bootsnap` if not already present
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: require-profiler
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.3.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Vladimir Dementyev
|
|
@@ -65,6 +65,20 @@ dependencies:
|
|
|
65
65
|
- - ">="
|
|
66
66
|
- !ruby/object:Gem::Version
|
|
67
67
|
version: '0'
|
|
68
|
+
- !ruby/object:Gem::Dependency
|
|
69
|
+
name: railties
|
|
70
|
+
requirement: !ruby/object:Gem::Requirement
|
|
71
|
+
requirements:
|
|
72
|
+
- - ">="
|
|
73
|
+
- !ruby/object:Gem::Version
|
|
74
|
+
version: '7.2'
|
|
75
|
+
type: :development
|
|
76
|
+
prerelease: false
|
|
77
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
78
|
+
requirements:
|
|
79
|
+
- - ">="
|
|
80
|
+
- !ruby/object:Gem::Version
|
|
81
|
+
version: '7.2'
|
|
68
82
|
- !ruby/object:Gem::Dependency
|
|
69
83
|
name: rake
|
|
70
84
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -134,8 +148,10 @@ files:
|
|
|
134
148
|
- lib/equire-prof.rb
|
|
135
149
|
- lib/require-profiler.rb
|
|
136
150
|
- lib/require_profiler.rb
|
|
151
|
+
- lib/require_profiler/patcher.rb
|
|
137
152
|
- lib/require_profiler/plugins.rb
|
|
138
153
|
- lib/require_profiler/plugins/http_plugin.rb
|
|
154
|
+
- lib/require_profiler/plugins/rails_plugin.rb
|
|
139
155
|
- lib/require_profiler/plugins/yaml_plugin.rb
|
|
140
156
|
- lib/require_profiler/printer.rb
|
|
141
157
|
- lib/require_profiler/printer/call_stack.rb
|
|
@@ -144,6 +160,7 @@ files:
|
|
|
144
160
|
- lib/require_profiler/reporter.rb
|
|
145
161
|
- lib/require_profiler/ruby_profiling.rb
|
|
146
162
|
- lib/require_profiler/version.rb
|
|
163
|
+
- skills/rails-boot-profiling/SKILL.md
|
|
147
164
|
homepage: https://github.com/palkan/require-profiler
|
|
148
165
|
licenses:
|
|
149
166
|
- MIT
|
|
@@ -153,6 +170,9 @@ metadata:
|
|
|
153
170
|
documentation_uri: https://github.com/palkan/require-profiler
|
|
154
171
|
homepage_uri: https://github.com/palkan/require-profiler
|
|
155
172
|
source_code_uri: https://github.com/palkan/require-profiler
|
|
173
|
+
hyperdrive_targets: railties
|
|
174
|
+
hyperdrive_artifacts: skill
|
|
175
|
+
hyperdrive_skills_dir: "./skills"
|
|
156
176
|
rdoc_options: []
|
|
157
177
|
require_paths:
|
|
158
178
|
- lib
|
|
@@ -167,7 +187,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
167
187
|
- !ruby/object:Gem::Version
|
|
168
188
|
version: '0'
|
|
169
189
|
requirements: []
|
|
170
|
-
rubygems_version:
|
|
190
|
+
rubygems_version: 4.0.16
|
|
171
191
|
specification_version: 4
|
|
172
192
|
summary: 'Profile Ruby #require/#load/etc calls'
|
|
173
193
|
test_files: []
|