ruby-prof 0.8.2 → 0.9.0
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGES +23 -13
- data/{README → README.rdoc} +118 -111
- data/Rakefile +14 -26
- data/bin/ruby-prof +16 -4
- data/examples/empty.png +0 -0
- data/examples/graph.dot +106 -0
- data/examples/graph.png +0 -0
- data/examples/minus.png +0 -0
- data/examples/multi.flat.txt +23 -0
- data/examples/multi.graph.html +906 -0
- data/examples/multi.grind.dat +194 -0
- data/examples/multi.stack.html +573 -0
- data/examples/plus.png +0 -0
- data/examples/stack.html +573 -0
- data/ext/ruby_prof/extconf.rb +0 -1
- data/ext/ruby_prof/measure_allocations.h +6 -6
- data/ext/ruby_prof/measure_cpu_time.h +5 -5
- data/ext/ruby_prof/measure_gc_runs.h +1 -1
- data/ext/ruby_prof/measure_gc_time.h +1 -1
- data/ext/ruby_prof/measure_memory.h +4 -4
- data/ext/ruby_prof/measure_process_time.h +1 -1
- data/ext/ruby_prof/measure_wall_time.h +1 -1
- data/ext/ruby_prof/ruby_prof.c +240 -167
- data/ext/ruby_prof/ruby_prof.h +12 -10
- data/ext/ruby_prof/version.h +3 -3
- data/lib/ruby-prof.rb +7 -1
- data/lib/ruby-prof/abstract_printer.rb +5 -5
- data/lib/ruby-prof/aggregate_call_info.rb +9 -3
- data/lib/ruby-prof/call_info.rb +66 -1
- data/lib/ruby-prof/call_stack_printer.rb +751 -0
- data/lib/ruby-prof/call_tree_printer.rb +2 -2
- data/lib/ruby-prof/dot_printer.rb +151 -0
- data/lib/ruby-prof/empty.png +0 -0
- data/lib/ruby-prof/flat_printer.rb +16 -16
- data/lib/ruby-prof/flat_printer_with_line_numbers.rb +13 -13
- data/lib/ruby-prof/graph_html_printer.rb +58 -36
- data/lib/ruby-prof/graph_printer.rb +30 -30
- data/lib/ruby-prof/method_info.rb +24 -4
- data/lib/ruby-prof/minus.png +0 -0
- data/lib/ruby-prof/multi_printer.rb +54 -0
- data/lib/ruby-prof/plus.png +0 -0
- data/lib/ruby-prof/rack.rb +28 -0
- data/lib/ruby-prof/result.rb +70 -0
- data/lib/ruby-prof/symbol_to_proc.rb +1 -1
- data/lib/ruby-prof/task.rb +19 -19
- data/lib/ruby-prof/test.rb +3 -3
- data/lib/ruby_prof.so +0 -0
- data/rails/environment/profile.rb +2 -2
- data/rails/example/example_test.rb +2 -2
- data/rails/profile_test_helper.rb +1 -1
- data/test/aggregate_test.rb +21 -6
- data/test/basic_test.rb +3 -3
- data/test/duplicate_names_test.rb +2 -2
- data/test/enumerable_test.rb +2 -2
- data/test/exceptions_test.rb +2 -2
- data/test/exclude_threads_test.rb +45 -45
- data/test/exec_test.rb +2 -2
- data/test/line_number_test.rb +11 -11
- data/test/measurement_test.rb +4 -3
- data/test/method_elimination_test.rb +74 -0
- data/test/module_test.rb +7 -7
- data/test/multi_printer_test.rb +81 -0
- data/test/no_method_class_test.rb +2 -2
- data/test/prime.rb +7 -10
- data/test/printers_test.rb +57 -47
- data/test/recursive_test.rb +23 -62
- data/test/singleton_test.rb +3 -2
- data/test/stack_printer_test.rb +74 -0
- data/test/stack_test.rb +1 -1
- data/test/start_stop_test.rb +2 -2
- data/test/test_suite.rb +9 -0
- data/test/thread_test.rb +17 -17
- data/test/unique_call_path_test.rb +4 -4
- metadata +29 -8
data/CHANGES
CHANGED
@@ -1,3 +1,13 @@
|
|
1
|
+
0.9.0
|
2
|
+
=======================
|
3
|
+
* measurements for recursive methods are now correct
|
4
|
+
* gave up on splitting up recursive methods according to call depth
|
5
|
+
* made it possible to eliminate methods from profiling results
|
6
|
+
* new printer for call stack visualization
|
7
|
+
* new printer to print several profiles in one run
|
8
|
+
* HTML profiles contain Textmate links so you can jump to the source code easily
|
9
|
+
* producing an event log is now a runtime option
|
10
|
+
|
1
11
|
0.7.10 (2009-01-22)
|
2
12
|
=======================
|
3
13
|
* fix SEGFAULT in 1.9
|
@@ -55,29 +65,29 @@
|
|
55
65
|
|
56
66
|
Features
|
57
67
|
--------
|
58
|
-
* Added two new methods - RubyProf.resume and RubyProf.pause.
|
68
|
+
* Added two new methods - RubyProf.resume and RubyProf.pause.
|
59
69
|
RubyProf.resume takes an optional block, which ensures that
|
60
70
|
RubyProf.pause is called. For example:
|
61
|
-
|
71
|
+
|
62
72
|
10.times do |i|
|
63
73
|
RubyProf.resume do
|
64
74
|
# Some long process
|
65
75
|
end
|
66
76
|
end
|
67
|
-
|
77
|
+
|
68
78
|
result = RubyProf.stop
|
69
79
|
|
70
80
|
* Added support for profiling tests that use Ruby's built-in
|
71
|
-
unit test framework (ie, test derived from
|
81
|
+
unit test framework (ie, test derived from
|
72
82
|
Test::Unit::TestCase). To enable profiling simply add
|
73
83
|
the following line of code to your test class:
|
74
|
-
|
84
|
+
|
75
85
|
include RubyProf::Test
|
76
|
-
|
77
|
-
By default, profiling results are written to the current
|
86
|
+
|
87
|
+
By default, profiling results are written to the current
|
78
88
|
processes working directory. To change this, or other
|
79
89
|
profiling options, simply modify the PROFILE_OPTIONS hash
|
80
|
-
table as needed.
|
90
|
+
table as needed.
|
81
91
|
|
82
92
|
* Used the new support for profiling test cases to revamp
|
83
93
|
the way that Rails profiling works. For more information
|
@@ -93,8 +103,8 @@ Features
|
|
93
103
|
|
94
104
|
* Add support for Lloyd Hilaiel's Ruby patch for measuring total heap size.
|
95
105
|
See http://lloydforge.org/projects/ruby. (Jeremy Kemper).
|
96
|
-
|
97
|
-
|
106
|
+
|
107
|
+
|
98
108
|
Fixes
|
99
109
|
-------
|
100
110
|
* RubyProf.profile no longer crashes if an exception is
|
@@ -102,7 +112,7 @@ Fixes
|
|
102
112
|
|
103
113
|
* Measure memory in fractional kilobytes rather than rounding down (Jeremy Kemper)
|
104
114
|
|
105
|
-
|
115
|
+
|
106
116
|
0.6.0 (2008-02-03)
|
107
117
|
========================
|
108
118
|
|
@@ -122,7 +132,7 @@ Fixes
|
|
122
132
|
fixes for min_time support, ability to specify templates using
|
123
133
|
strings or filenames, and table layout fixes (Makoto Kuwata)
|
124
134
|
* Fixes to scaling factor for calltrees so that precision is not lost
|
125
|
-
due to the conversion to doubles (Sylvain Joyeux)
|
135
|
+
due to the conversion to doubles (Sylvain Joyeux)
|
126
136
|
* Changed constant ALLOCATED_OBJECTS to ALLOCATIONS in the C code to
|
127
137
|
match the Ruby code (Sylvain Joyeux)
|
128
138
|
* Added support for calltree printer to ruby-prof binary script (Sylvain Joyeux)
|
@@ -132,7 +142,7 @@ Fixes
|
|
132
142
|
* Fix ruby-prof to work with the latest version of GEMS (Alexander Dymo)
|
133
143
|
* Always define MEASURE_CPU_TIME and MEASURE_ALLOCATIONS in Ruby code, but
|
134
144
|
set their values to nil if the functionality is not available.
|
135
|
-
|
145
|
+
|
136
146
|
|
137
147
|
0.5.2 (2007-07-19)
|
138
148
|
========================
|
data/{README → README.rdoc}
RENAMED
@@ -5,14 +5,12 @@
|
|
5
5
|
ruby-prof is a fast code profiler for Ruby. Its features include:
|
6
6
|
|
7
7
|
* Speed - it is a C extension and therefore many times faster than the standard Ruby profiler.
|
8
|
-
* Modes - Ruby prof can measure a number of different parameters, including
|
9
|
-
call times, memory usage and object allocations.
|
8
|
+
* Modes - Ruby prof can measure a number of different parameters, including call times, memory usage and object allocations.
|
10
9
|
* Reports - can generate text and cross-referenced html reports
|
11
10
|
- Flat Profiles - similar to the reports generated by the standard Ruby profiler
|
12
11
|
- Graph profiles - similar to GProf, these show how long a method runs, which methods call it and which methods it calls.
|
13
12
|
- Call tree profiles - outputs results in the calltree format suitable for the KCacheGrind profiling tool.
|
14
13
|
* Threads - supports profiling multiple threads simultaneously
|
15
|
-
* Recursive calls - supports profiling recursive method calls
|
16
14
|
|
17
15
|
|
18
16
|
== Requirements
|
@@ -22,17 +20,17 @@ ruby-prof requires Ruby 1.8.4 or higher.
|
|
22
20
|
If you are running Linux or Unix you'll need a C compiler so the extension
|
23
21
|
can be compiled when it is installed.
|
24
22
|
|
25
|
-
If you are running Windows, then you may need to install the
|
23
|
+
If you are running Windows, then you may need to install the
|
26
24
|
Windows specific RubyGem which includes an already built extension (see below).
|
27
25
|
|
28
26
|
== Install
|
29
27
|
|
30
28
|
The easiest way to install ruby-prof is by using Ruby Gems. To install:
|
31
29
|
|
32
|
-
|
30
|
+
gem install ruby-prof
|
33
31
|
|
34
|
-
If you on windows mswin [not mingw] (check via ruby -v) and
|
35
|
-
don't have an MSVC compiler, please install v0.7.3 which
|
32
|
+
If you on windows mswin [not mingw] (check via ruby -v) and
|
33
|
+
don't have an MSVC compiler, please install v0.7.3 which
|
36
34
|
has a prebuilt binary
|
37
35
|
C:> gem install ruby-prof -v0.7.3
|
38
36
|
|
@@ -44,41 +42,41 @@ There are three ways of running ruby-prof.
|
|
44
42
|
|
45
43
|
=== ruby-prof executable
|
46
44
|
|
47
|
-
The first is to use ruby-prof to run the Ruby program
|
48
|
-
|
49
|
-
|
45
|
+
The first is to use ruby-prof to run the Ruby program you want to
|
46
|
+
profile. For more information refer to the documentation of the
|
47
|
+
ruby-prof command.
|
50
48
|
|
51
49
|
|
52
50
|
=== ruby-prof API
|
53
51
|
|
54
52
|
The second way is to use the ruby-prof API to profile
|
55
|
-
particular segments of code.
|
53
|
+
particular segments of code.
|
56
54
|
|
57
55
|
require 'ruby-prof'
|
58
|
-
|
56
|
+
|
59
57
|
# Profile the code
|
60
58
|
RubyProf.start
|
61
59
|
...
|
62
60
|
[code to profile]
|
63
61
|
...
|
64
62
|
result = RubyProf.stop
|
65
|
-
|
63
|
+
|
66
64
|
# Print a flat profile to text
|
67
65
|
printer = RubyProf::FlatPrinter.new(result)
|
68
66
|
printer.print(STDOUT)
|
69
|
-
|
67
|
+
|
70
68
|
Alternatively, you can use a block to tell ruby-prof what
|
71
69
|
to profile:
|
72
70
|
|
73
71
|
require 'ruby-prof'
|
74
|
-
|
72
|
+
|
75
73
|
# Profile the code
|
76
74
|
result = RubyProf.profile do
|
77
75
|
...
|
78
76
|
[code to profile]
|
79
77
|
...
|
80
78
|
end
|
81
|
-
|
79
|
+
|
82
80
|
# Print a graph profile to text
|
83
81
|
printer = RubyProf::GraphPrinter.new(result)
|
84
82
|
printer.print(STDOUT, 0)
|
@@ -87,7 +85,7 @@ Starting with the 0.6.1 release, ruby-prof also supports pausing and resuming
|
|
87
85
|
profiling runs.
|
88
86
|
|
89
87
|
require 'ruby-prof'
|
90
|
-
|
88
|
+
|
91
89
|
# Profile the code
|
92
90
|
RubyProf.start
|
93
91
|
[code to profile]
|
@@ -96,20 +94,20 @@ profiling runs.
|
|
96
94
|
RubyProf.resume
|
97
95
|
[code to profile]
|
98
96
|
result = RubyProf.stop
|
99
|
-
|
97
|
+
|
100
98
|
Note that resume will automatically call start if a profiling run
|
101
99
|
has not yet started. In addition, resume can also take a block:
|
102
100
|
|
103
101
|
require 'ruby-prof'
|
104
|
-
|
102
|
+
|
105
103
|
# Profile the code
|
106
104
|
RubyProf.resume do
|
107
105
|
[code to profile]
|
108
106
|
end
|
109
107
|
|
110
108
|
data = RubyProf.stop
|
111
|
-
|
112
|
-
With this usage, resume will automatically call pause at the
|
109
|
+
|
110
|
+
With this usage, resume will automatically call pause at the
|
113
111
|
end of the block.
|
114
112
|
|
115
113
|
|
@@ -122,33 +120,55 @@ The third way of using ruby-prof is by requiring unprof.rb:
|
|
122
120
|
This will start profiling immediately and will output the results
|
123
121
|
using a flat profile report.
|
124
122
|
|
125
|
-
This method is provided for backwards compatibility. Using
|
126
|
-
|
123
|
+
This method is provided for backwards compatibility. Using the
|
124
|
+
ruby-prof command provides more flexibility.
|
125
|
+
|
126
|
+
== Method Elimination
|
127
|
+
|
128
|
+
Starting with release 0.9.0, ruby-prof supports eliminating methods from profiling
|
129
|
+
results. This is useful for reducing connectivity in the call graph, making it easier to
|
130
|
+
identify the source of performance problems when using a graph printer.
|
131
|
+
|
132
|
+
For example, consider Integer#times: it's hardly ever useful to know how much time is
|
133
|
+
spent in the method itself. We're much more interested in how much the passed in block
|
134
|
+
contributes to the time spent in the method which contains the Integer#times call.
|
135
|
+
|
136
|
+
Methods are eliminated from the collected data by calling `eliminate_methods!` on the
|
137
|
+
profiling result, before submitting it to a printer.
|
138
|
+
|
139
|
+
result = RubyProf.stop
|
140
|
+
result.eliminate_methods!([/Integer#times/])
|
141
|
+
|
142
|
+
The argument given to `eliminate_methods!` is either an array of regular expressions, or
|
143
|
+
the name of a file containing a list of regular expressions (line separated text).
|
144
|
+
|
145
|
+
After eliminating methods the resulting profile will appear exactly as if those methods
|
146
|
+
had been inlined at their call sites.
|
127
147
|
|
128
148
|
|
129
149
|
== Profiling Tests
|
130
150
|
|
131
151
|
Starting with the 0.6.1 release, ruby-prof supports profiling tests cases
|
132
|
-
written using Ruby's built-in unit test framework (ie, test derived from
|
133
|
-
Test::Unit::TestCase). To enable profiling simply add the following line
|
152
|
+
written using Ruby's built-in unit test framework (ie, test derived from
|
153
|
+
Test::Unit::TestCase). To enable profiling simply add the following line
|
134
154
|
of code to within your test class:
|
135
|
-
|
136
|
-
|
137
|
-
|
155
|
+
|
156
|
+
include RubyProf::Test
|
157
|
+
|
138
158
|
Each test method is profiled separately. ruby-prof will run each test method
|
139
159
|
once as a warmup and then ten additional times to gather profile data.
|
140
|
-
Note that the profile data will *not* include the class's setup or
|
160
|
+
Note that the profile data will *not* include the class's setup or
|
141
161
|
teardown methods.
|
142
162
|
|
143
|
-
Separate reports are generated for each method and saved, by default,
|
163
|
+
Separate reports are generated for each method and saved, by default,
|
144
164
|
in the test process's working directory. To change this, or other profiling
|
145
|
-
options, modify your test class's PROFILE_OPTIONS hash table. To globally
|
146
|
-
change test profiling options, modify RubyProf::Test::PROFILE_OPTIONS.
|
165
|
+
options, modify your test class's PROFILE_OPTIONS hash table. To globally
|
166
|
+
change test profiling options, modify RubyProf::Test::PROFILE_OPTIONS.
|
147
167
|
|
148
168
|
|
149
169
|
== Profiling Rails
|
150
170
|
|
151
|
-
To profile a Rails application it is vital to run it using production like
|
171
|
+
To profile a Rails application it is vital to run it using production like
|
152
172
|
settings (cache classes, cache view lookups, etc.). Otherwise, Rail's
|
153
173
|
dependency loading code will overwhelm any time spent in the application
|
154
174
|
itself (our tests show that Rails dependency loading causes a roughly 6x
|
@@ -159,47 +179,47 @@ So to profile Rails:
|
|
159
179
|
|
160
180
|
1. Create a new profile.rb environment - or simply copy the example file
|
161
181
|
in ruby-prof/rails/environment/profile.rb
|
162
|
-
|
182
|
+
|
163
183
|
2. Copy the file:
|
164
|
-
|
165
|
-
ruby-prof/rails/profile_test_helper.rb
|
166
|
-
|
184
|
+
|
185
|
+
ruby-prof/rails/profile_test_helper.rb
|
186
|
+
|
167
187
|
To:
|
168
|
-
|
188
|
+
|
169
189
|
your_rails_app/test/profile_test_helper.rb
|
170
190
|
|
171
191
|
3. Create a new test directory for profiling:
|
172
192
|
|
173
193
|
your_rails_app/test/profile
|
174
|
-
|
194
|
+
|
175
195
|
|
176
196
|
4. Write unit, functional or integration tests specifically designed
|
177
197
|
to profile some part of your Rails application. At the top
|
178
198
|
of each test, replace this line:
|
179
|
-
|
199
|
+
|
180
200
|
require File.dirname(__FILE__) + '/../test_helper'
|
181
201
|
|
182
202
|
With:
|
183
|
-
|
203
|
+
|
184
204
|
require File.dirname(__FILE__) + '/../profile_test_helper'
|
185
205
|
|
186
206
|
For example:
|
187
207
|
|
188
208
|
require File.dirname(__FILE__) + '/../profile_test_helper'
|
189
|
-
|
209
|
+
|
190
210
|
class ExampleTest < Test::Unit::TestCase
|
191
211
|
include RubyProf::Test
|
192
212
|
fixtures ....
|
193
|
-
|
213
|
+
|
194
214
|
def test_stuff
|
195
215
|
puts "Test method"
|
196
216
|
end
|
197
|
-
end
|
217
|
+
end
|
198
218
|
|
199
219
|
5. Now run your tests. Results will be written to:
|
200
220
|
|
201
221
|
your_rails_app/tmp/profile
|
202
|
-
|
222
|
+
|
203
223
|
|
204
224
|
== Reports
|
205
225
|
|
@@ -209,35 +229,39 @@ ruby-prof can generate a number of different reports:
|
|
209
229
|
* Graph Reports
|
210
230
|
* HTML Graph Reports
|
211
231
|
* Call graphs
|
232
|
+
* Call stack reports
|
212
233
|
|
213
|
-
Flat profiles show the overall time spent in each method.
|
234
|
+
Flat profiles show the overall time spent in each method. They
|
214
235
|
are a good of quickly identifying which methods take the most time.
|
215
236
|
An example of a flat profile and an explanation can be found in
|
216
|
-
{examples/flat.txt}[
|
217
|
-
|
218
|
-
Graph profiles also show the overall time spent in each method.
|
219
|
-
|
220
|
-
|
221
|
-
|
222
|
-
|
223
|
-
|
224
|
-
|
225
|
-
HTML Graph profiles are the same as graph profiles, except
|
226
|
-
|
227
|
-
|
228
|
-
|
229
|
-
|
230
|
-
|
231
|
-
HTML Graph profiles are the same as graph profiles, except
|
232
|
-
output is generated in hyper-linked HTML. Since graph profiles
|
233
|
-
can be quite large, the embedded links make it much easier to
|
234
|
-
navigate the results. An example html graph profile
|
235
|
-
is located at {examples/graph.html}[link:files/examples/graph_html.html].
|
237
|
+
{examples/flat.txt}[http://github.com/rdp/ruby-prof/tree/master/examples/flat.txt].
|
238
|
+
|
239
|
+
Graph profiles also show the overall time spent in each method. In
|
240
|
+
addition, they also show which methods call the current method and which
|
241
|
+
methods its calls. Thus they are good for understanding how methods
|
242
|
+
gets called and provide insight into the flow of your program. An
|
243
|
+
example text graph profile is located at
|
244
|
+
{examples/graph.txt}[http://github.com/rdp/ruby-prof/tree/master/examples/graph.txt].
|
245
|
+
|
246
|
+
HTML Graph profiles are the same as graph profiles, except output is
|
247
|
+
generated in hyper-linked HTML. Since graph profiles can be quite large,
|
248
|
+
the embedded links make it much easier to navigate the results. An
|
249
|
+
example html graph profile is located at
|
250
|
+
{examples/graph.html}[http://github.com/rdp/ruby-prof/tree/master/examples/graph.html].
|
236
251
|
|
237
252
|
Call graphs output results in the calltree profile format which is used
|
238
|
-
by KCachegrind.
|
239
|
-
More information about the format can be found at
|
240
|
-
|
253
|
+
by KCachegrind. Call graph support was generously donated by Carl
|
254
|
+
Shimer. More information about the format can be found at the
|
255
|
+
{KCachegrind}[http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat]
|
256
|
+
site.
|
257
|
+
|
258
|
+
Call stack reports produce a HTML visualization of the time spent in
|
259
|
+
each execution path of the profiled code. An example can be found at
|
260
|
+
{examples/stack.html}[http://github.com/rdp/ruby-prof/tree/master/examples/call_stack.html].
|
261
|
+
|
262
|
+
Finally, there's a so called MultiPrinter which can generate several
|
263
|
+
reports in one profiling run. See
|
264
|
+
{examples/multi.stack.html}[http://github.com/rdp/ruby-prof/tree/master/examples/multi.stack.html].
|
241
265
|
|
242
266
|
|
243
267
|
== Printers
|
@@ -248,7 +272,10 @@ Reports are created by printers. Supported printers include:
|
|
248
272
|
* RubyProf::FlatPrinterWithLineNumbers - same as above but more verbose
|
249
273
|
* RubyProf::GraphPrinter - Creates a call graph report in text format
|
250
274
|
* RubyProf::GraphHtmlPrinter - Creates a call graph report in HTML (separate files per thread)
|
275
|
+
* RubyProf::DotPrinter - Creates a call graph report in GraphViz's DOT format which can be converted to an image
|
251
276
|
* RubyProf::CallTreePrinter - Creates a call tree report compatible with KCachegrind.
|
277
|
+
* RubyProf::CallStackPrinter - Creates a HTML visualization of the Ruby stack
|
278
|
+
* RubyProf::MultiPrinter - Uses the other printers to create several reports in one profiling run
|
252
279
|
|
253
280
|
To use a printer:
|
254
281
|
|
@@ -258,13 +285,20 @@ To use a printer:
|
|
258
285
|
printer.print(STDOUT, :min_percent => 2)
|
259
286
|
|
260
287
|
The first parameter is any writable IO object such as STDOUT or a file.
|
261
|
-
The second parameter, specifies the minimum percentage a method must take
|
262
|
-
to be printed. Percentages should be specified as integers in the range 0 to 100.
|
288
|
+
The second parameter, specifies the minimum percentage a method must take
|
289
|
+
to be printed. Percentages should be specified as integers in the range 0 to 100.
|
263
290
|
For more information please see the documentation for the different printers.
|
264
291
|
|
265
292
|
The other option is :print_file => true (default false), which adds the filename to the
|
266
293
|
output (GraphPrinter only).
|
267
294
|
|
295
|
+
The MultiPrinter differs from the other printers in that it requires a directory path
|
296
|
+
and a basename for the files it produces.
|
297
|
+
|
298
|
+
printer = RubyProf::MultiPrinter.new(result)
|
299
|
+
printer.print(:path => ".", :profile => "profile")
|
300
|
+
|
301
|
+
|
268
302
|
== Measurements
|
269
303
|
|
270
304
|
Depending on the mode and platform, ruby-prof can measure various
|
@@ -279,7 +313,7 @@ aspects of a Ruby program. Supported measurements include:
|
|
279
313
|
* garbage collection time (RubyProf::GC_TIME)
|
280
314
|
|
281
315
|
Process time measures the time used by a process between any two moments.
|
282
|
-
It is unaffected by other processes concurrently running
|
316
|
+
It is unaffected by other processes concurrently running
|
283
317
|
on the system. Note that Windows does not support measuring process
|
284
318
|
times - therefore, measurements on Windows defaults to wall time.
|
285
319
|
|
@@ -335,17 +369,17 @@ environment variable:
|
|
335
369
|
* export RUBY_PROF_MEASURE_MODE=memory
|
336
370
|
* export RUBY_PROF_MEASURE_MODE=gc_runs
|
337
371
|
* export RUBY_PROF_MEASURE_MODE=gc_time
|
338
|
-
|
339
|
-
Note that these values have changed since ruby-prof-0.3.0.
|
340
372
|
|
341
|
-
|
373
|
+
Note that these values have changed since ruby-prof-0.3.0.
|
374
|
+
|
375
|
+
On Linux, process time is measured using the clock method provided
|
342
376
|
by the C runtime library. Note that the clock method does not
|
343
377
|
report time spent in the kernel or child processes and therefore
|
344
378
|
does not measure time spent in methods such as Kernel.sleep method.
|
345
379
|
If you need to measure these values, then use wall time. Wall time
|
346
380
|
is measured using the gettimeofday kernel method.
|
347
381
|
|
348
|
-
On Windows, timings default to wall times. If you set the clock
|
382
|
+
On Windows, timings default to wall times. If you set the clock
|
349
383
|
mode to PROCESS_TIME, then timing are read using the clock method
|
350
384
|
provided by the C runtime library. Note though, these values are
|
351
385
|
wall times on Windows and not process times like on Linux.
|
@@ -354,62 +388,35 @@ Wall time is measured using the GetLocalTime API.
|
|
354
388
|
If you use wall time, the results will be affected by other
|
355
389
|
processes running on your computer, network delays, disk access,
|
356
390
|
etc. As result, for the best results, try to make sure your
|
357
|
-
computer is only performing your profiling run and is
|
391
|
+
computer is only performing your profiling run and is
|
358
392
|
otherwise quiescent.
|
359
393
|
|
360
394
|
On both platforms, cpu time is measured using the RDTSC assembly
|
361
395
|
function provided by the Pentium and PowerPC platforms. CPU time
|
362
|
-
is dependent on the cpu's frequency. On Linux, ruby-prof attempts
|
396
|
+
is dependent on the cpu's frequency. On Linux, ruby-prof attempts
|
363
397
|
to read this value from "/proc/cpuinfo." On Windows, you must
|
364
398
|
manually specify the clock frequency. This can be done using the
|
365
399
|
RUBY_PROF_CPU_FREQUENCY environment variable:
|
366
400
|
|
367
401
|
export RUBY_PROF_CPU_FREQUENCY=<value>
|
368
|
-
|
369
|
-
You can also directly set the cpu frequency by calling:
|
370
|
-
|
371
|
-
RubyProf.cpu_frequency = <value>
|
372
402
|
|
403
|
+
You can also directly set the cpu frequency by calling:
|
373
404
|
|
374
|
-
|
375
|
-
|
376
|
-
Recursive calls occur when method A calls method A and cycles
|
377
|
-
occur when method A calls method B calls method C calls method A.
|
378
|
-
ruby-prof detects both direct recursive calls and cycles. Both
|
379
|
-
are indicated in reports by a "d number" in parentheses following a method
|
380
|
-
name. For example, here is a flat profile from the test method
|
381
|
-
|
382
|
-
RecursiveTest#test_recursive:
|
383
|
-
|
384
|
-
%self total self wait child calls name
|
385
|
-
100.00 2.00 2.00 0.00 0.00 2 Kernel#sleep
|
386
|
-
0.00 2.00 0.00 0.00 2.00 0 RecursiveTest#test_cycle
|
387
|
-
0.00 0.00 0.00 0.00 0.00 2 Fixnum#==
|
388
|
-
0.00 0.00 0.00 0.00 0.00 2 Fixnum#-
|
389
|
-
0.00 1.00 0.00 0.00 1.00 1 Object#sub_cycle(d1)
|
390
|
-
0.00 2.00 0.00 0.00 2.00 1 Object#sub_cycle
|
391
|
-
0.00 2.00 0.00 0.00 2.00 1 Object#cycle
|
392
|
-
0.00 1.00 0.00 0.00 1.00 1 Object#cycle(d1)
|
393
|
-
|
394
|
-
Notice the presence of Object#cycle and Object#cycle(d1). The d1 means
|
395
|
-
depth 1 -- the method was either recursively called (directly or indirectly).
|
405
|
+
RubyProf.cpu_frequency = <value>
|
396
406
|
|
397
|
-
However, the self time values for recursive calls should always
|
398
|
-
be accurate. It is also believed that the total times are
|
399
|
-
accurate, but these should be carefully analyzed to verify their veracity.
|
400
407
|
|
401
408
|
== Multi-threaded Applications
|
402
409
|
|
403
410
|
Unfortunately, Ruby does not provide an internal api
|
404
411
|
for detecting thread context switches in 1.8. As a result, the
|
405
412
|
timings ruby-prof reports for each thread may be slightly
|
406
|
-
inaccurate. In particular, this will happen for newly
|
407
|
-
spawned threads that go to sleep immediately (their first call).
|
413
|
+
inaccurate. In particular, this will happen for newly
|
414
|
+
spawned threads that go to sleep immediately (their first call).
|
408
415
|
For instance, if you use Ruby's timeout library to wait for 2 seconds,
|
409
416
|
the 2 seconds will be assigned to the foreground thread
|
410
417
|
and not the newly created background thread. These errors
|
411
418
|
can largely be avoided if the background thread performs any
|
412
|
-
operation before going to sleep.
|
419
|
+
operation before going to sleep.
|
413
420
|
|
414
421
|
== Performance
|
415
422
|
|
@@ -429,4 +436,4 @@ See LICENSE for license information.
|
|
429
436
|
|
430
437
|
== Development
|
431
438
|
|
432
|
-
Code is located at http://github.com/rdp/ruby-prof
|
439
|
+
Code is located at http://github.com/rdp/ruby-prof
|