ruby-prof 2.0.0 → 2.0.1

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.
data/docs/reports.md CHANGED
@@ -1,150 +1,150 @@
1
- # Reports
2
-
3
- Once you have completed a profiling run, you will want to generate a report to analyze the results. One of ruby-prof's strengths is the number of ways it lets you visualize profiling results, from quick text summaries to interactive HTML views and external tooling formats. The following table shows all supported report types and when to use them:
4
-
5
- For repeatable profiling workflow guidance, see [Best Practices](best-practices.md).
6
-
7
- | Name | Best For |
8
- |---|---|
9
- | `FlatPrinter` | Finding hottest methods fast (best quick signal by self time) |
10
- | `GraphPrinter` | Understanding who called a hot method (caller/callee context in text) |
11
- | `GraphHtmlPrinter` | Exploring large call graphs interactively (clickable navigation) |
12
- | `FlameGraphPrinter` | Seeing hot paths visually (where time accumulates) |
13
- | `CallStackPrinter` | Inspecting execution-path dominance (tree of major runtime paths) |
14
- | `CallTreePrinter` | Using external profiler tooling (KCachegrind/callgrind format) |
15
- | `CallInfoPrinter` | Debugging ruby-prof internals/data shape (low-level call-tree details) |
16
- | `MultiPrinter` | Generating several outputs at once (one run, multiple files) |
17
-
18
- Recommended workflow:
19
-
20
- 1. Run `FlatPrinter` to find top offenders.
21
- 2. Use `GraphHtmlPrinter` (or `GraphPrinter`) to understand caller/callee relationships.
22
- 3. Use `FlameGraphPrinter` to visually validate dominant paths.
23
-
24
- ## Creating Reports
25
-
26
- Reports are created via the use of printers:
27
-
28
- ```ruby
29
- profile = RubyProf::Profile.profile do
30
- ...
31
- end
32
- printer = RubyProf::GraphPrinter.new(profile)
33
- printer.print(STDOUT, min_percent: 2)
34
- ```
35
-
36
- The first parameter is any writable IO object such as STDOUT or a file. All printers accept the following keyword arguments:
37
-
38
- | Option | Default | Description |
39
- |--------|---------|-------------|
40
- | `min_percent` | `0` | Minimum %self time for a method to be included (0–100). |
41
- | `max_percent` | `100` | Maximum %self time for a method to be included (0–100). |
42
- | `filter_by` | `:self_time` | Which time metric to use when applying `min_percent` and `max_percent`. |
43
- | `sort_method` | varies | How to sort methods. Values: `:total_time`, `:self_time`, `:wait_time`, `:children_time`. |
44
-
45
- ## Report Types
46
-
47
- ### Flat
48
-
49
- The flat report shows the overall time spent in each method. It is a good way of quickly identifying which methods take the most time. Use `RubyProf::FlatPrinter` to generate this report. Default `sort_method` is `:self_time`. (<a href="../public/examples/reports/flat.txt" target="_blank">example</a>)
50
-
51
- ![Flat Report](../public/images/flat.png)
52
-
53
- ### Graph (Text)
54
-
55
- The graph report shows the overall time spent in each method. In addition, it also shows which methods call the current method and which methods it calls. Thus they are good for understanding how methods get called and provide insight into the flow of your program. Use `RubyProf::GraphPrinter` to generate this report. Default `sort_method` is `:total_time`. (<a href="../public/examples/reports/graph.txt" target="_blank">example</a>)
56
-
57
- ![Graph Report](../public/images/graph.png)
58
-
59
- ### Graph (HTML)
60
-
61
- HTML Graph profiles are the same as graph reports, except output is generated in hyper-linked HTML. Since graph reports can be quite large, the embedded links make it much easier to navigate the results. Use `RubyProf::GraphHtmlPrinter` to generate this report. Default `sort_method` is `:total_time`. (<a href="../public/examples/reports/graph.html" target="_blank">example</a>)
62
-
63
- ![HTML Graph Report](../public/images/graph_html.png)
64
-
65
- Additional options:
66
-
67
- | Option | Default | Description |
68
- |--------|---------|-------------|
69
- | `min_time` | `nil` | Minimum total time (in seconds) for a method to be shown. |
70
- | `nonzero` | `false` | When `true`, sets `min_time` to 0.005 if `min_time` is not specified. |
71
-
72
- ### Flame Graph
73
-
74
- Flame graph reports produce a self-contained HTML visualization of the profiled code. Each method is represented as a horizontal bar whose width is proportional to its total time. Bars are stacked vertically by call depth, making it easy to identify hot code paths at a glance. A toggle switches between flame (bottom-up) and icicle (top-down) views. Use `RubyProf::FlameGraphPrinter` to generate this report. (<a href="../public/examples/reports/flame_graph.html" target="_blank">example</a>)
75
-
76
- ![Flame Graph](../public/images/flame_graph.png)
77
-
78
- Interactive features include hover tooltips (showing method name, self time, total time, percentage, and call count), click-to-zoom into a subtree, a reset zoom button, a search box to highlight matching methods, and a thread selector when multiple threads are profiled.
79
-
80
- ```ruby
81
- printer = RubyProf::FlameGraphPrinter.new(result)
82
- printer.print(File.open("flame_graph.html", "w"))
83
- ```
84
-
85
- Additional options:
86
-
87
- | Option | Default | Description |
88
- |--------|---------|-------------|
89
- | `title` | `"ruby-prof flame graph"` | Title displayed in the HTML report. |
90
-
91
- ### Call Stack
92
-
93
- Call stack reports produce a HTML visualization of the time spent in each execution path of the profiled code. Use `RubyProf::CallStackPrinter` to generate this report. (<a href="../public/examples/reports/call_stack.html" target="_blank">example</a>)
94
-
95
- ![Call Stack Report](../public/images/call_stack.png)
96
-
97
- Additional options:
98
-
99
- | Option | Default | Description |
100
- |--------|---------|-------------|
101
- | `title` | `"ruby-prof call stack"` | Title displayed in the HTML report. |
102
- | `threshold` | `1.0` | Minimum %total for a node to be visible (0–100). |
103
- | `expansion` | `10.0` | Minimum %total for a node to be expanded by default (0–100). |
104
- | `application` | `$PROGRAM_NAME` | Application name displayed in the report. |
105
-
106
- ### Graphviz
107
-
108
- The graphviz report is designed to be opened by [Graphviz](https://www.graphviz.org/) to create visualization of profile results. The output can be visualized using the [Graphviz Online](https://dreampuf.github.io/GraphvizOnline/) viewer. Use `RubyProf::DotPrinter` to generate this report. (<a href="../public/examples/reports/graph.dot" target="_blank">example</a>, <a href="../public/examples/reports/graphviz_viewer.html" target="_blank">view online</a>)
109
-
110
- ![Graphviz Report](../public/images/dot_printer.png)
111
-
112
- ### Cachegrind
113
-
114
- Cachegrind output results in the calltree profile format which is used by [KCachegrind](https://kcachegrind.github.io/html/Home.html). More information about the format can be found at the KCachegrind site. Use `RubyProf::CallTreePrinter` to generate this report. (<a href="../public/examples/reports/callgrind.out" target="_blank">example</a>)
115
-
116
- Additional options:
117
-
118
- | Option | Default | Description |
119
- |--------|---------|-------------|
120
- | `path` | `"."` | Directory where callgrind output files are written. |
121
-
122
- ### Call Info Report
123
-
124
- Call info reports print the call tree with timing information for each node. This is mainly useful for debugging purposes as it provides access into ruby-prof's internals. Use `RubyProf::CallInfoPrinter` to generate this report. (<a href="../public/examples/reports/call_info.txt" target="_blank">example</a>)
125
-
126
- ### Multiple Reports
127
-
128
- `RubyProf::MultiPrinter` can generate several reports in one profiling run. It requires a directory path and a profile basename for the files it produces:
129
-
130
- ```ruby
131
- printer = RubyProf::MultiPrinter.new(result)
132
- printer.print(path: ".", profile: "profile")
133
- ```
134
-
135
- | Option | Default | Description |
136
- |--------|---------|-------------|
137
- | `path` | `"."` | Directory where report files are written. |
138
- | `profile` | `"profile"` | Base filename for the generated reports. |
139
-
140
- All other keyword arguments are forwarded to the individual printers.
141
-
142
- ## Generating Examples
143
-
144
- To regenerate the example reports:
145
-
146
- ```
147
- ruby docs/public/examples/generate_reports.rb
148
- ```
149
-
150
- This profiles a small word-frequency workload and writes reports to `docs/public/examples/reports/`.
1
+ # Reports
2
+
3
+ Once you have completed a profiling run, you will want to generate a report to analyze the results. One of ruby-prof's strengths is the number of ways it lets you visualize profiling results, from quick text summaries to interactive HTML views and external tooling formats. The following table shows all supported report types and when to use them:
4
+
5
+ For repeatable profiling workflow guidance, see [Best Practices](best-practices.md).
6
+
7
+ | Name | Best For |
8
+ |---|---|
9
+ | `FlatPrinter` | Finding hottest methods fast (best quick signal by self time) |
10
+ | `GraphPrinter` | Understanding who called a hot method (caller/callee context in text) |
11
+ | `GraphHtmlPrinter` | Exploring large call graphs interactively (clickable navigation) |
12
+ | `FlameGraphPrinter` | Seeing hot paths visually (where time accumulates) |
13
+ | `CallStackPrinter` | Inspecting execution-path dominance (tree of major runtime paths) |
14
+ | `CallTreePrinter` | Using external profiler tooling (KCachegrind/callgrind format) |
15
+ | `CallInfoPrinter` | Debugging ruby-prof internals/data shape (low-level call-tree details) |
16
+ | `MultiPrinter` | Generating several outputs at once (one run, multiple files) |
17
+
18
+ Recommended workflow:
19
+
20
+ 1. Run `FlatPrinter` to find top offenders.
21
+ 2. Use `GraphHtmlPrinter` (or `GraphPrinter`) to understand caller/callee relationships.
22
+ 3. Use `FlameGraphPrinter` to visually validate dominant paths.
23
+
24
+ ## Creating Reports
25
+
26
+ Reports are created via the use of printers:
27
+
28
+ ```ruby
29
+ profile = RubyProf::Profile.profile do
30
+ ...
31
+ end
32
+ printer = RubyProf::GraphPrinter.new(profile)
33
+ printer.print(STDOUT, min_percent: 2)
34
+ ```
35
+
36
+ The first parameter is any writable IO object such as STDOUT or a file. All printers accept the following keyword arguments:
37
+
38
+ | Option | Default | Description |
39
+ |--------|---------|-------------|
40
+ | `min_percent` | `0` | Minimum %self time for a method to be included (0–100). |
41
+ | `max_percent` | `100` | Maximum %self time for a method to be included (0–100). |
42
+ | `filter_by` | `:self_time` | Which time metric to use when applying `min_percent` and `max_percent`. |
43
+ | `sort_method` | varies | How to sort methods. Values: `:total_time`, `:self_time`, `:wait_time`, `:children_time`. |
44
+
45
+ ## Report Types
46
+
47
+ ### Flat
48
+
49
+ The flat report shows the overall time spent in each method. It is a good way of quickly identifying which methods take the most time. Use `RubyProf::FlatPrinter` to generate this report. Default `sort_method` is `:self_time`. (<a href="../public/examples/reports/flat.txt" target="_blank">example</a>)
50
+
51
+ ![Flat Report](../public/images/flat.png)
52
+
53
+ ### Graph (Text)
54
+
55
+ The graph report shows the overall time spent in each method. In addition, it also shows which methods call the current method and which methods it calls. Thus they are good for understanding how methods get called and provide insight into the flow of your program. Use `RubyProf::GraphPrinter` to generate this report. Default `sort_method` is `:total_time`. (<a href="../public/examples/reports/graph.txt" target="_blank">example</a>)
56
+
57
+ ![Graph Report](../public/images/graph.png)
58
+
59
+ ### Graph (HTML)
60
+
61
+ HTML Graph profiles are the same as graph reports, except output is generated in hyper-linked HTML. Since graph reports can be quite large, the embedded links make it much easier to navigate the results. Use `RubyProf::GraphHtmlPrinter` to generate this report. Default `sort_method` is `:total_time`. (<a href="../public/examples/reports/graph.html" target="_blank">example</a>)
62
+
63
+ ![HTML Graph Report](../public/images/graph_html.png)
64
+
65
+ Additional options:
66
+
67
+ | Option | Default | Description |
68
+ |--------|---------|-------------|
69
+ | `min_time` | `nil` | Minimum total time (in seconds) for a method to be shown. |
70
+ | `nonzero` | `false` | When `true`, sets `min_time` to 0.005 if `min_time` is not specified. |
71
+
72
+ ### Flame Graph
73
+
74
+ Flame graph reports produce a self-contained HTML visualization of the profiled code. Each method is represented as a horizontal bar whose width is proportional to its total time. Bars are stacked vertically by call depth, making it easy to identify hot code paths at a glance. A toggle switches between flame (bottom-up) and icicle (top-down) views. Use `RubyProf::FlameGraphPrinter` to generate this report. (<a href="../public/examples/reports/flame_graph.html" target="_blank">example</a>)
75
+
76
+ ![Flame Graph](../public/images/flame_graph.png)
77
+
78
+ Interactive features include hover tooltips (showing method name, self time, total time, percentage, and call count), click-to-zoom into a subtree, a reset zoom button, a search box to highlight matching methods, and a thread selector when multiple threads are profiled.
79
+
80
+ ```ruby
81
+ printer = RubyProf::FlameGraphPrinter.new(result)
82
+ printer.print(File.open("flame_graph.html", "w"))
83
+ ```
84
+
85
+ Additional options:
86
+
87
+ | Option | Default | Description |
88
+ |--------|---------|-------------|
89
+ | `title` | `"ruby-prof flame graph"` | Title displayed in the HTML report. |
90
+
91
+ ### Call Stack
92
+
93
+ Call stack reports produce a HTML visualization of the time spent in each execution path of the profiled code. Use `RubyProf::CallStackPrinter` to generate this report. (<a href="../public/examples/reports/call_stack.html" target="_blank">example</a>)
94
+
95
+ ![Call Stack Report](../public/images/call_stack.png)
96
+
97
+ Additional options:
98
+
99
+ | Option | Default | Description |
100
+ |--------|---------|-------------|
101
+ | `title` | `"ruby-prof call stack"` | Title displayed in the HTML report. |
102
+ | `threshold` | `1.0` | Minimum %total for a node to be visible (0–100). |
103
+ | `expansion` | `10.0` | Minimum %total for a node to be expanded by default (0–100). |
104
+ | `application` | `$PROGRAM_NAME` | Application name displayed in the report. |
105
+
106
+ ### Graphviz
107
+
108
+ The graphviz report is designed to be opened by [Graphviz](https://www.graphviz.org/) to create visualization of profile results. The output can be visualized using the [Graphviz Online](https://dreampuf.github.io/GraphvizOnline/) viewer. Use `RubyProf::DotPrinter` to generate this report. (<a href="../public/examples/reports/graph.dot" target="_blank">example</a>, <a href="../public/examples/reports/graphviz_viewer.html" target="_blank">view online</a>)
109
+
110
+ ![Graphviz Report](../public/images/dot_printer.png)
111
+
112
+ ### Cachegrind
113
+
114
+ Cachegrind output results in the calltree profile format which is used by [KCachegrind](https://kcachegrind.github.io/html/Home.html). More information about the format can be found at the KCachegrind site. Use `RubyProf::CallTreePrinter` to generate this report. (<a href="../public/examples/reports/callgrind.out" target="_blank">example</a>)
115
+
116
+ Additional options:
117
+
118
+ | Option | Default | Description |
119
+ |--------|---------|-------------|
120
+ | `path` | `"."` | Directory where callgrind output files are written. |
121
+
122
+ ### Call Info Report
123
+
124
+ Call info reports print the call tree with timing information for each node. This is mainly useful for debugging purposes as it provides access into ruby-prof's internals. Use `RubyProf::CallInfoPrinter` to generate this report. (<a href="../public/examples/reports/call_info.txt" target="_blank">example</a>)
125
+
126
+ ### Multiple Reports
127
+
128
+ `RubyProf::MultiPrinter` can generate several reports in one profiling run. It requires a directory path and a profile basename for the files it produces:
129
+
130
+ ```ruby
131
+ printer = RubyProf::MultiPrinter.new(result)
132
+ printer.print(path: ".", profile: "profile")
133
+ ```
134
+
135
+ | Option | Default | Description |
136
+ |--------|---------|-------------|
137
+ | `path` | `"."` | Directory where report files are written. |
138
+ | `profile` | `"profile"` | Base filename for the generated reports. |
139
+
140
+ All other keyword arguments are forwarded to the individual printers.
141
+
142
+ ## Generating Examples
143
+
144
+ To regenerate the example reports:
145
+
146
+ ```
147
+ ruby docs/public/examples/generate_reports.rb
148
+ ```
149
+
150
+ This profiles a small word-frequency workload and writes reports to `docs/public/examples/reports/`.
@@ -1,3 +1,3 @@
1
1
  module RubyProf
2
- VERSION = "2.0.0"
2
+ VERSION = "2.0.1"
3
3
  end
data/ruby-prof.gemspec CHANGED
@@ -1,66 +1,66 @@
1
- # -*- encoding: utf-8 -*-
2
-
3
- $:.push File.expand_path("../lib", __FILE__)
4
- require "ruby-prof/version"
5
-
6
- Gem::Specification.new do |spec|
7
- spec.name = "ruby-prof"
8
-
9
- spec.homepage = "https://github.com/ruby-prof/ruby-prof/"
10
- spec.summary = "Fast Ruby profiler"
11
- spec.description = <<-EOF
12
- ruby-prof is a fast code profiler for Ruby. It is a C extension and
13
- therefore is many times faster than the standard Ruby profiler. It
14
- supports both flat and graph profiles. For each method, graph profiles
15
- show how long the method ran, which methods called it and which
16
- methods it called. RubyProf generate both text and html and can output
17
- it to standard out or to a file.
18
- EOF
19
- spec.license = 'BSD-2-Clause'
20
- spec.version = RubyProf::VERSION
21
-
22
- spec.metadata = {
23
- "bug_tracker_uri" => "https://github.com/ruby-prof/ruby-prof/issues",
24
- "changelog_uri" => "https://github.com/ruby-prof/ruby-prof/blob/master/CHANGELOG.md",
25
- "documentation_uri" => "https://ruby-prof.github.io/",
26
- "source_code_uri" => "https://github.com/ruby-prof/ruby-prof/tree/v#{spec.version}",
27
- }
28
-
29
- spec.author = "Shugo Maeda, Charlie Savage, Roger Pack, Stefan Kaes"
30
- spec.email = "shugo@ruby-lang.org, cfis@savagexi.com, rogerdpack@gmail.com, skaes@railsexpress.de"
31
- spec.platform = Gem::Platform::RUBY
32
- spec.require_path = "lib"
33
- spec.bindir = "bin"
34
- spec.executables = ["ruby-prof", "ruby-prof-check-trace"]
35
- spec.extensions = ["ext/ruby_prof/extconf.rb"]
36
- spec.files = Dir['CHANGELOG.md',
37
- 'LICENSE',
38
- 'Rakefile',
39
- 'README.md',
40
- 'ruby-prof.gemspec',
41
- 'bin/ruby-prof',
42
- 'bin/ruby-prof-check-trace',
43
- 'docs/**/*',
44
- 'ext/ruby_prof/extconf.rb',
45
- 'ext/ruby_prof/*.c',
46
- 'ext/ruby_prof/*.h',
47
- 'ext/ruby_prof/vc/*.sln',
48
- 'ext/ruby_prof/vc/*.vcxproj',
49
- 'lib/ruby-prof.rb',
50
- 'lib/unprof.rb',
51
- 'lib/ruby-prof/*.rb',
52
- 'lib/ruby-prof/assets/*',
53
- 'lib/ruby-prof/profile/*.rb',
54
- 'lib/ruby-prof/printers/*.rb',
55
- 'test/*.rb']
56
-
57
- spec.test_files = Dir["test/test_*.rb"]
58
- spec.required_ruby_version = '>= 3.2.0'
59
- spec.date = Time.now.strftime('%Y-%m-%d')
60
- spec.homepage = 'https://github.com/ruby-prof/ruby-prof'
61
- spec.add_dependency('base64')
62
- spec.add_dependency('ostruct')
63
- spec.add_development_dependency('minitest')
64
- spec.add_development_dependency('rake-compiler')
65
- spec.add_development_dependency('rdoc')
66
- end
1
+ # -*- encoding: utf-8 -*-
2
+
3
+ $:.push File.expand_path("../lib", __FILE__)
4
+ require "ruby-prof/version"
5
+
6
+ Gem::Specification.new do |spec|
7
+ spec.name = "ruby-prof"
8
+
9
+ spec.homepage = "https://github.com/ruby-prof/ruby-prof/"
10
+ spec.summary = "Fast Ruby profiler"
11
+ spec.description = <<-EOF
12
+ ruby-prof is a fast code profiler for Ruby. It is a C extension and
13
+ therefore is many times faster than the standard Ruby profiler. It
14
+ supports both flat and graph profiles. For each method, graph profiles
15
+ show how long the method ran, which methods called it and which
16
+ methods it called. RubyProf generate both text and html and can output
17
+ it to standard out or to a file.
18
+ EOF
19
+ spec.license = 'BSD-2-Clause'
20
+ spec.version = RubyProf::VERSION
21
+
22
+ spec.metadata = {
23
+ "bug_tracker_uri" => "https://github.com/ruby-prof/ruby-prof/issues",
24
+ "changelog_uri" => "https://github.com/ruby-prof/ruby-prof/blob/master/CHANGELOG.md",
25
+ "documentation_uri" => "https://ruby-prof.github.io/",
26
+ "source_code_uri" => "https://github.com/ruby-prof/ruby-prof/tree/v#{spec.version}",
27
+ }
28
+
29
+ spec.author = "Shugo Maeda, Charlie Savage, Roger Pack, Stefan Kaes"
30
+ spec.email = "shugo@ruby-lang.org, cfis@savagexi.com, rogerdpack@gmail.com, skaes@railsexpress.de"
31
+ spec.platform = Gem::Platform::RUBY
32
+ spec.require_path = "lib"
33
+ spec.bindir = "bin"
34
+ spec.executables = ["ruby-prof", "ruby-prof-check-trace"]
35
+ spec.extensions = ["ext/ruby_prof/extconf.rb"]
36
+ spec.files = Dir['CHANGELOG.md',
37
+ 'LICENSE',
38
+ 'Rakefile',
39
+ 'README.md',
40
+ 'ruby-prof.gemspec',
41
+ 'bin/ruby-prof',
42
+ 'bin/ruby-prof-check-trace',
43
+ 'docs/**/*',
44
+ 'ext/ruby_prof/extconf.rb',
45
+ 'ext/ruby_prof/*.c',
46
+ 'ext/ruby_prof/*.h',
47
+ 'ext/ruby_prof/vc/*.sln',
48
+ 'ext/ruby_prof/vc/*.vcxproj',
49
+ 'lib/ruby-prof.rb',
50
+ 'lib/unprof.rb',
51
+ 'lib/ruby-prof/*.rb',
52
+ 'lib/ruby-prof/assets/*',
53
+ 'lib/ruby-prof/profile/*.rb',
54
+ 'lib/ruby-prof/printers/*.rb',
55
+ 'test/*.rb']
56
+
57
+ spec.test_files = Dir["test/test_*.rb"]
58
+ spec.required_ruby_version = '>= 3.2.0'
59
+ spec.date = Time.now.strftime('%Y-%m-%d')
60
+ spec.homepage = 'https://github.com/ruby-prof/ruby-prof'
61
+ spec.add_dependency('base64')
62
+ spec.add_dependency('ostruct')
63
+ spec.add_development_dependency('minitest')
64
+ spec.add_development_dependency('rake-compiler')
65
+ spec.add_development_dependency('rdoc')
66
+ end