acunote-ruby-prof 0.9.2
Sign up to get free protection for your applications and to get access to all the features.
- data/CHANGES +240 -0
- data/LICENSE +23 -0
- data/README.rdoc +439 -0
- data/Rakefile +148 -0
- data/bin/ruby-prof +236 -0
- data/examples/empty.png +0 -0
- data/examples/flat.txt +55 -0
- data/examples/graph.dot +106 -0
- data/examples/graph.html +823 -0
- data/examples/graph.png +0 -0
- data/examples/graph.txt +170 -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 +43 -0
- data/ext/ruby_prof/measure_allocations.h +58 -0
- data/ext/ruby_prof/measure_cpu_time.h +152 -0
- data/ext/ruby_prof/measure_gc_runs.h +76 -0
- data/ext/ruby_prof/measure_gc_time.h +57 -0
- data/ext/ruby_prof/measure_memory.h +101 -0
- data/ext/ruby_prof/measure_process_time.h +52 -0
- data/ext/ruby_prof/measure_wall_time.h +53 -0
- data/ext/ruby_prof/mingw/Rakefile +23 -0
- data/ext/ruby_prof/mingw/build.rake +38 -0
- data/ext/ruby_prof/ruby_prof.c +1834 -0
- data/ext/ruby_prof/ruby_prof.h +190 -0
- data/ext/ruby_prof/version.h +4 -0
- data/lib/ruby-prof.rb +62 -0
- data/lib/ruby-prof/abstract_printer.rb +41 -0
- data/lib/ruby-prof/aggregate_call_info.rb +68 -0
- data/lib/ruby-prof/call_info.rb +112 -0
- data/lib/ruby-prof/call_stack_printer.rb +751 -0
- data/lib/ruby-prof/call_tree_printer.rb +133 -0
- data/lib/ruby-prof/dot_printer.rb +153 -0
- data/lib/ruby-prof/empty.png +0 -0
- data/lib/ruby-prof/flat_printer.rb +78 -0
- data/lib/ruby-prof/flat_printer_with_line_numbers.rb +72 -0
- data/lib/ruby-prof/graph_html_printer.rb +278 -0
- data/lib/ruby-prof/graph_printer.rb +245 -0
- data/lib/ruby-prof/method_info.rb +131 -0
- 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 +30 -0
- data/lib/ruby-prof/result.rb +70 -0
- data/lib/ruby-prof/symbol_to_proc.rb +8 -0
- data/lib/ruby-prof/task.rb +146 -0
- data/lib/ruby-prof/test.rb +148 -0
- data/lib/unprof.rb +8 -0
- data/rails/environment/profile.rb +24 -0
- data/rails/example/example_test.rb +9 -0
- data/rails/profile_test_helper.rb +21 -0
- data/test/aggregate_test.rb +136 -0
- data/test/basic_test.rb +290 -0
- data/test/current_failures_windows +8 -0
- data/test/do_nothing.rb +0 -0
- data/test/duplicate_names_test.rb +32 -0
- data/test/enumerable_test.rb +16 -0
- data/test/exceptions_test.rb +15 -0
- data/test/exclude_threads_test.rb +54 -0
- data/test/exec_test.rb +14 -0
- data/test/line_number_test.rb +73 -0
- data/test/measurement_test.rb +122 -0
- data/test/method_elimination_test.rb +74 -0
- data/test/module_test.rb +44 -0
- data/test/multi_printer_test.rb +81 -0
- data/test/no_method_class_test.rb +13 -0
- data/test/prime.rb +55 -0
- data/test/prime_test.rb +13 -0
- data/test/printers_test.rb +164 -0
- data/test/recursive_test.rb +236 -0
- data/test/ruby-prof-bin +20 -0
- data/test/singleton_test.rb +38 -0
- data/test/stack_printer_test.rb +74 -0
- data/test/stack_test.rb +138 -0
- data/test/start_stop_test.rb +112 -0
- data/test/test_suite.rb +32 -0
- data/test/thread_test.rb +173 -0
- data/test/unique_call_path_test.rb +225 -0
- metadata +185 -0
data/CHANGES
ADDED
@@ -0,0 +1,240 @@
|
|
1
|
+
0.9.2
|
2
|
+
=======================
|
3
|
+
Make graphviz work on 1.8.6
|
4
|
+
roll back some 1.9.2 optimizations until I can figure out what caused them.
|
5
|
+
|
6
|
+
0.9.1
|
7
|
+
=======================
|
8
|
+
Add a graphviz output
|
9
|
+
|
10
|
+
0.9.0
|
11
|
+
=======================
|
12
|
+
* measurements for recursive methods are now correct
|
13
|
+
* gave up on splitting up recursive methods according to call depth
|
14
|
+
* made it possible to eliminate methods from profiling results
|
15
|
+
* new printer for call stack visualization
|
16
|
+
* new printer to print several profiles in one run
|
17
|
+
* HTML profiles contain Textmate links so you can jump to the source code easily
|
18
|
+
* producing an event log is now a runtime option
|
19
|
+
|
20
|
+
0.7.10 (2009-01-22)
|
21
|
+
=======================
|
22
|
+
* fix SEGFAULT in 1.9
|
23
|
+
* add new printer flat_printer_with_line_numbers
|
24
|
+
|
25
|
+
0.7.7 (2009-01-13)
|
26
|
+
======================
|
27
|
+
* "fix" multi threading support for 1.9 http://redmine.ruby-lang.org/issues/show/2012
|
28
|
+
* speedups
|
29
|
+
|
30
|
+
0.7.6 (2009-12-31)
|
31
|
+
======================
|
32
|
+
* fix some tests for 1.9 (no real code changes)
|
33
|
+
|
34
|
+
0.7.5 (2009-12)
|
35
|
+
========================
|
36
|
+
* fix a GC collection bug (nobu's patch).
|
37
|
+
* correctly report recursive call depths (Kevin Scaldeferri).
|
38
|
+
* sort methods on output (Kevin Scaldeferri).
|
39
|
+
|
40
|
+
0.7.3 (2008-12-09)
|
41
|
+
========================
|
42
|
+
* Fixed compile error with new x86_64 code using GCC.
|
43
|
+
|
44
|
+
0.7.2 (2008-12-08)
|
45
|
+
========================
|
46
|
+
* Fixed major bug in printing child methods in graph reports.
|
47
|
+
|
48
|
+
* Fixes for supporting x86_64 machines (Diego Pettenò)
|
49
|
+
|
50
|
+
|
51
|
+
0.7.1 (2008-11-28)
|
52
|
+
========================
|
53
|
+
* Added new AggregateCallInfo class for printers to
|
54
|
+
make results easier to read. Take this call sequence
|
55
|
+
for example:
|
56
|
+
|
57
|
+
A B C
|
58
|
+
| | |
|
59
|
+
Z A A
|
60
|
+
| |
|
61
|
+
Z Z
|
62
|
+
|
63
|
+
By default, ruby-prof will show that Z was called by 3 separate
|
64
|
+
instances of A. In an IDE that is helpful but in a text report
|
65
|
+
it is not since it makes the report much harder to read.
|
66
|
+
As a result, printers now aggregate together callers (and children),
|
67
|
+
matching ruby-prof's output from versions prior to 0.7.0.
|
68
|
+
|
69
|
+
* Fixes for supporting x86_64 machines (Matt Sanford)
|
70
|
+
|
71
|
+
|
72
|
+
0.7.0 (2008-11-04)
|
73
|
+
========================
|
74
|
+
|
75
|
+
Features
|
76
|
+
--------
|
77
|
+
* Added two new methods - RubyProf.resume and RubyProf.pause.
|
78
|
+
RubyProf.resume takes an optional block, which ensures that
|
79
|
+
RubyProf.pause is called. For example:
|
80
|
+
|
81
|
+
10.times do |i|
|
82
|
+
RubyProf.resume do
|
83
|
+
# Some long process
|
84
|
+
end
|
85
|
+
end
|
86
|
+
|
87
|
+
result = RubyProf.stop
|
88
|
+
|
89
|
+
* Added support for profiling tests that use Ruby's built-in
|
90
|
+
unit test framework (ie, test derived from
|
91
|
+
Test::Unit::TestCase). To enable profiling simply add
|
92
|
+
the following line of code to your test class:
|
93
|
+
|
94
|
+
include RubyProf::Test
|
95
|
+
|
96
|
+
By default, profiling results are written to the current
|
97
|
+
processes working directory. To change this, or other
|
98
|
+
profiling options, simply modify the PROFILE_OPTIONS hash
|
99
|
+
table as needed.
|
100
|
+
|
101
|
+
* Used the new support for profiling test cases to revamp
|
102
|
+
the way that Rails profiling works. For more information
|
103
|
+
please refer to RubyProf's documentation.
|
104
|
+
|
105
|
+
* Keep track of call stack for each method to enable more
|
106
|
+
powerful profile visualizations in Integrated Development
|
107
|
+
Environments (Hin Boean, work supported by CodeGear).
|
108
|
+
|
109
|
+
* Expose measurements to Ruby (Jeremy Kemper).
|
110
|
+
|
111
|
+
* Add support for additional memory measurements modes in Ruby 1.9 (Jeremy Kemper).
|
112
|
+
|
113
|
+
* Add support for Lloyd Hilaiel's Ruby patch for measuring total heap size.
|
114
|
+
See http://lloydforge.org/projects/ruby. (Jeremy Kemper).
|
115
|
+
|
116
|
+
|
117
|
+
Fixes
|
118
|
+
-------
|
119
|
+
* RubyProf.profile no longer crashes if an exception is
|
120
|
+
thrown during a profiling run.
|
121
|
+
|
122
|
+
* Measure memory in fractional kilobytes rather than rounding down (Jeremy Kemper)
|
123
|
+
|
124
|
+
|
125
|
+
0.6.0 (2008-02-03)
|
126
|
+
========================
|
127
|
+
|
128
|
+
ruby-prof 0.6.0 adds support for Ruby 1.9 and memory profiling.
|
129
|
+
|
130
|
+
Features
|
131
|
+
--------
|
132
|
+
* Added support for ruby 1.9 (Shugo Maeda)
|
133
|
+
* Added support for outputting printer results to a String, Array or IO
|
134
|
+
object (Michael Granger)
|
135
|
+
* Add new memory profiling mode. Note this mode depends on a
|
136
|
+
patched Ruby interpreter (Alexander Dymo)
|
137
|
+
|
138
|
+
Fixes
|
139
|
+
-------
|
140
|
+
* Improvements to GraphHtmlPrinter including updated documentation,
|
141
|
+
fixes for min_time support, ability to specify templates using
|
142
|
+
strings or filenames, and table layout fixes (Makoto Kuwata)
|
143
|
+
* Fixes to scaling factor for calltrees so that precision is not lost
|
144
|
+
due to the conversion to doubles (Sylvain Joyeux)
|
145
|
+
* Changed constant ALLOCATED_OBJECTS to ALLOCATIONS in the C code to
|
146
|
+
match the Ruby code (Sylvain Joyeux)
|
147
|
+
* Added support for calltree printer to ruby-prof binary script (Sylvain Joyeux)
|
148
|
+
* Fix support for the allocator measure mode to extconf.rb (Sylvain Joyeux)
|
149
|
+
* Honor measure mode when specified on the command line (Sylvain Joyeux)
|
150
|
+
* Sorting of methods by total time was incorrect (Dan Fitch, Charlie Savage)
|
151
|
+
* Fix ruby-prof to work with the latest version of GEMS (Alexander Dymo)
|
152
|
+
* Always define MEASURE_CPU_TIME and MEASURE_ALLOCATIONS in Ruby code, but
|
153
|
+
set their values to nil if the functionality is not available.
|
154
|
+
|
155
|
+
|
156
|
+
0.5.2 (2007-07-19)
|
157
|
+
========================
|
158
|
+
|
159
|
+
ruby-prof 0.5.2 is a bug fix release.
|
160
|
+
|
161
|
+
Fixes
|
162
|
+
-------
|
163
|
+
* Include missing rails plugin
|
164
|
+
|
165
|
+
|
166
|
+
0.5.1 (2007-07-18)
|
167
|
+
========================
|
168
|
+
|
169
|
+
ruby-prof 0.5.1 is a bug fix and performance release.
|
170
|
+
|
171
|
+
Performance
|
172
|
+
--------
|
173
|
+
* Significantly reduced the number of thread lookups by
|
174
|
+
caching the last executed thread.
|
175
|
+
|
176
|
+
Fixes
|
177
|
+
-------
|
178
|
+
* Properly escape method names in HTML reports
|
179
|
+
* Fix use of -m and --min-percent command line switches
|
180
|
+
* Default source file information to ruby_runtime#0 for c calls
|
181
|
+
* Moved rails_plugin to top level so it is more obvious
|
182
|
+
* Updated rails_plugin to write reports to the current
|
183
|
+
Rails log directory
|
184
|
+
* Added additional tests
|
185
|
+
|
186
|
+
|
187
|
+
0.5.0 (2007-07-09)
|
188
|
+
========================
|
189
|
+
|
190
|
+
Features
|
191
|
+
--------
|
192
|
+
* Added support for timing multi-threaded applications
|
193
|
+
* Added support for 64 bit systems (patch from Diego 'Flameeyes' Petten)
|
194
|
+
* Added suport for outputting data in the format used by
|
195
|
+
KCacheGrind (patch from Carl Shimer)
|
196
|
+
* Add filename and line numbers to call tree information (patch from Carl Shimer)
|
197
|
+
* Added Visual Studio 2005 project file.
|
198
|
+
* Added replace-progname switch, als rcov.
|
199
|
+
* Added better support for recursive methods
|
200
|
+
* Added better support for profiling Rails applications
|
201
|
+
|
202
|
+
Fixes
|
203
|
+
-------
|
204
|
+
* Fixes bug when the type of an attached object (singleton) is inherited
|
205
|
+
from T_OBJECT as opposed to being a T_OBJECT (identified by Francis Cianfrocca)
|
206
|
+
* ruby-prof now works in IRB.
|
207
|
+
* Fix sort order in reports.
|
208
|
+
* Fixed rdoc compile error.
|
209
|
+
* Fix tabs in erb template for graph html report on windows.
|
210
|
+
|
211
|
+
0.4.1 (2006-06-26)
|
212
|
+
========================
|
213
|
+
|
214
|
+
Features
|
215
|
+
--------
|
216
|
+
* Added a RubyProf.running? method to indicate whether a profile is in progress.
|
217
|
+
* Added tgz and zip archives to release
|
218
|
+
|
219
|
+
Fixes
|
220
|
+
-------
|
221
|
+
* Duplicate method names are now allowed
|
222
|
+
* The documentation has been updated to show the correct API usage is RubyProf.stop not RubyProf.end
|
223
|
+
|
224
|
+
|
225
|
+
0.4.0 (2006-06-16)
|
226
|
+
========================
|
227
|
+
Features
|
228
|
+
--------
|
229
|
+
* added support for call graphs
|
230
|
+
* added support for printers. Currently there is a FlatPrinter,
|
231
|
+
GraphPrinter and GraphHtmlPrinter.
|
232
|
+
* added support for recursive methods
|
233
|
+
* added Windows support
|
234
|
+
* now packaged as a RubyGem
|
235
|
+
|
236
|
+
Fixes
|
237
|
+
-------
|
238
|
+
* Fixes bug where RubyProf would crash depending on the
|
239
|
+
way it was invoked - for example, it did not run when
|
240
|
+
used with Arachno Ruby's customized version of Ruby.
|
data/LICENSE
ADDED
@@ -0,0 +1,23 @@
|
|
1
|
+
Copyright (C) 2005 Shugo Maeda <shugo@ruby-lang.org>
|
2
|
+
All rights reserved.
|
3
|
+
*
|
4
|
+
Redistribution and use in source and binary forms, with or without
|
5
|
+
modification, are permitted provided that the following conditions
|
6
|
+
are met:
|
7
|
+
1. Redistributions of source code must retain the above copyright
|
8
|
+
notice, this list of conditions and the following disclaimer.
|
9
|
+
2. Redistributions in binary form must reproduce the above copyright
|
10
|
+
notice, this list of conditions and the following disclaimer in the
|
11
|
+
documentation and/or other materials provided with the distribution.
|
12
|
+
*
|
13
|
+
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
14
|
+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
15
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
16
|
+
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
17
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
18
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
19
|
+
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
20
|
+
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
21
|
+
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
22
|
+
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
23
|
+
SUCH DAMAGE.
|
data/README.rdoc
ADDED
@@ -0,0 +1,439 @@
|
|
1
|
+
= ruby-prof
|
2
|
+
|
3
|
+
== Overview
|
4
|
+
|
5
|
+
ruby-prof is a fast code profiler for Ruby. Its features include:
|
6
|
+
|
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 call times, memory usage and object allocations.
|
9
|
+
* Reports - can generate text and cross-referenced html reports
|
10
|
+
- Flat Profiles - similar to the reports generated by the standard Ruby profiler
|
11
|
+
- Graph profiles - similar to GProf, these show how long a method runs, which methods call it and which methods it calls.
|
12
|
+
- Call tree profiles - outputs results in the calltree format suitable for the KCacheGrind profiling tool.
|
13
|
+
* Threads - supports profiling multiple threads simultaneously
|
14
|
+
|
15
|
+
|
16
|
+
== Requirements
|
17
|
+
|
18
|
+
ruby-prof requires Ruby 1.8.4 or higher.
|
19
|
+
|
20
|
+
If you are running Linux or Unix you'll need a C compiler so the extension
|
21
|
+
can be compiled when it is installed.
|
22
|
+
|
23
|
+
If you are running Windows, then you may need to install the
|
24
|
+
Windows specific RubyGem which includes an already built extension (see below).
|
25
|
+
|
26
|
+
== Install
|
27
|
+
|
28
|
+
The easiest way to install ruby-prof is by using Ruby Gems. To install:
|
29
|
+
|
30
|
+
gem install ruby-prof
|
31
|
+
|
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
|
34
|
+
has a prebuilt binary
|
35
|
+
C:> gem install ruby-prof -v0.7.3
|
36
|
+
|
37
|
+
If you're on mingw, please install the devkit first, then install the latest version (gem install ruby-prof).
|
38
|
+
|
39
|
+
== Usage
|
40
|
+
|
41
|
+
There are three ways of running ruby-prof.
|
42
|
+
|
43
|
+
=== ruby-prof executable
|
44
|
+
|
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.
|
48
|
+
|
49
|
+
|
50
|
+
=== ruby-prof API
|
51
|
+
|
52
|
+
The second way is to use the ruby-prof API to profile
|
53
|
+
particular segments of code.
|
54
|
+
|
55
|
+
require 'ruby-prof'
|
56
|
+
|
57
|
+
# Profile the code
|
58
|
+
RubyProf.start
|
59
|
+
...
|
60
|
+
[code to profile]
|
61
|
+
...
|
62
|
+
result = RubyProf.stop
|
63
|
+
|
64
|
+
# Print a flat profile to text
|
65
|
+
printer = RubyProf::FlatPrinter.new(result)
|
66
|
+
printer.print(STDOUT)
|
67
|
+
|
68
|
+
Alternatively, you can use a block to tell ruby-prof what
|
69
|
+
to profile:
|
70
|
+
|
71
|
+
require 'ruby-prof'
|
72
|
+
|
73
|
+
# Profile the code
|
74
|
+
result = RubyProf.profile do
|
75
|
+
...
|
76
|
+
[code to profile]
|
77
|
+
...
|
78
|
+
end
|
79
|
+
|
80
|
+
# Print a graph profile to text
|
81
|
+
printer = RubyProf::GraphPrinter.new(result)
|
82
|
+
printer.print(STDOUT, 0)
|
83
|
+
|
84
|
+
Starting with the 0.6.1 release, ruby-prof also supports pausing and resuming
|
85
|
+
profiling runs.
|
86
|
+
|
87
|
+
require 'ruby-prof'
|
88
|
+
|
89
|
+
# Profile the code
|
90
|
+
RubyProf.start
|
91
|
+
[code to profile]
|
92
|
+
RubyProf.pause
|
93
|
+
[other code]
|
94
|
+
RubyProf.resume
|
95
|
+
[code to profile]
|
96
|
+
result = RubyProf.stop
|
97
|
+
|
98
|
+
Note that resume will automatically call start if a profiling run
|
99
|
+
has not yet started. In addition, resume can also take a block:
|
100
|
+
|
101
|
+
require 'ruby-prof'
|
102
|
+
|
103
|
+
# Profile the code
|
104
|
+
RubyProf.resume do
|
105
|
+
[code to profile]
|
106
|
+
end
|
107
|
+
|
108
|
+
data = RubyProf.stop
|
109
|
+
|
110
|
+
With this usage, resume will automatically call pause at the
|
111
|
+
end of the block.
|
112
|
+
|
113
|
+
|
114
|
+
=== require unprof
|
115
|
+
|
116
|
+
The third way of using ruby-prof is by requiring unprof.rb:
|
117
|
+
|
118
|
+
require 'unprof'
|
119
|
+
|
120
|
+
This will start profiling immediately and will output the results
|
121
|
+
using a flat profile report.
|
122
|
+
|
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.
|
147
|
+
|
148
|
+
|
149
|
+
== Profiling Tests
|
150
|
+
|
151
|
+
Starting with the 0.6.1 release, ruby-prof supports profiling tests cases
|
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
|
154
|
+
of code to within your test class:
|
155
|
+
|
156
|
+
include RubyProf::Test
|
157
|
+
|
158
|
+
Each test method is profiled separately. ruby-prof will run each test method
|
159
|
+
once as a warmup and then ten additional times to gather profile data.
|
160
|
+
Note that the profile data will *not* include the class's setup or
|
161
|
+
teardown methods.
|
162
|
+
|
163
|
+
Separate reports are generated for each method and saved, by default,
|
164
|
+
in the test process's working directory. To change this, or other profiling
|
165
|
+
options, modify your test class's PROFILE_OPTIONS hash table. To globally
|
166
|
+
change test profiling options, modify RubyProf::Test::PROFILE_OPTIONS.
|
167
|
+
|
168
|
+
|
169
|
+
== Profiling Rails
|
170
|
+
|
171
|
+
To profile a Rails application it is vital to run it using production like
|
172
|
+
settings (cache classes, cache view lookups, etc.). Otherwise, Rail's
|
173
|
+
dependency loading code will overwhelm any time spent in the application
|
174
|
+
itself (our tests show that Rails dependency loading causes a roughly 6x
|
175
|
+
slowdown). The best way to do this is create a new Rails environment,
|
176
|
+
profile.rb.
|
177
|
+
|
178
|
+
So to profile Rails:
|
179
|
+
|
180
|
+
1. Create a new profile.rb environment - or simply copy the example file
|
181
|
+
in ruby-prof/rails/environment/profile.rb
|
182
|
+
|
183
|
+
2. Copy the file:
|
184
|
+
|
185
|
+
ruby-prof/rails/profile_test_helper.rb
|
186
|
+
|
187
|
+
To:
|
188
|
+
|
189
|
+
your_rails_app/test/profile_test_helper.rb
|
190
|
+
|
191
|
+
3. Create a new test directory for profiling:
|
192
|
+
|
193
|
+
your_rails_app/test/profile
|
194
|
+
|
195
|
+
|
196
|
+
4. Write unit, functional or integration tests specifically designed
|
197
|
+
to profile some part of your Rails application. At the top
|
198
|
+
of each test, replace this line:
|
199
|
+
|
200
|
+
require File.dirname(__FILE__) + '/../test_helper'
|
201
|
+
|
202
|
+
With:
|
203
|
+
|
204
|
+
require File.dirname(__FILE__) + '/../profile_test_helper'
|
205
|
+
|
206
|
+
For example:
|
207
|
+
|
208
|
+
require File.dirname(__FILE__) + '/../profile_test_helper'
|
209
|
+
|
210
|
+
class ExampleTest < Test::Unit::TestCase
|
211
|
+
include RubyProf::Test
|
212
|
+
fixtures ....
|
213
|
+
|
214
|
+
def test_stuff
|
215
|
+
puts "Test method"
|
216
|
+
end
|
217
|
+
end
|
218
|
+
|
219
|
+
5. Now run your tests. Results will be written to:
|
220
|
+
|
221
|
+
your_rails_app/tmp/profile
|
222
|
+
|
223
|
+
|
224
|
+
== Reports
|
225
|
+
|
226
|
+
ruby-prof can generate a number of different reports:
|
227
|
+
|
228
|
+
* Flat Reports
|
229
|
+
* Graph Reports
|
230
|
+
* HTML Graph Reports
|
231
|
+
* Call graphs
|
232
|
+
* Call stack reports
|
233
|
+
|
234
|
+
Flat profiles show the overall time spent in each method. They
|
235
|
+
are a good of quickly identifying which methods take the most time.
|
236
|
+
An example of a flat profile and an explanation can be found in
|
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].
|
251
|
+
|
252
|
+
Call graphs output results in the calltree profile format which is used
|
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].
|
265
|
+
|
266
|
+
|
267
|
+
== Printers
|
268
|
+
|
269
|
+
Reports are created by printers. Supported printers include:
|
270
|
+
|
271
|
+
* RubyProf::FlatPrinter - Creates a flat report in text format
|
272
|
+
* RubyProf::FlatPrinterWithLineNumbers - same as above but more verbose
|
273
|
+
* RubyProf::GraphPrinter - Creates a call graph report in text format
|
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
|
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
|
279
|
+
|
280
|
+
To use a printer:
|
281
|
+
|
282
|
+
...
|
283
|
+
result = RubyProf.end
|
284
|
+
printer = RubyProf::GraphPrinter.new(result)
|
285
|
+
printer.print(STDOUT, :min_percent => 2)
|
286
|
+
|
287
|
+
The first parameter is any writable IO object such as STDOUT or a file.
|
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.
|
290
|
+
For more information please see the documentation for the different printers.
|
291
|
+
|
292
|
+
The other option is :print_file => true (default false), which adds the filename to the
|
293
|
+
output (GraphPrinter only).
|
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
|
+
|
302
|
+
== Measurements
|
303
|
+
|
304
|
+
Depending on the mode and platform, ruby-prof can measure various
|
305
|
+
aspects of a Ruby program. Supported measurements include:
|
306
|
+
|
307
|
+
* process time (RubyProf::PROCESS_TIME)
|
308
|
+
* wall time (RubyProf::WALL_TIME)
|
309
|
+
* cpu time (RubyProf::CPU_TIME)
|
310
|
+
* object allocations (RubyProf::ALLOCATIONS)
|
311
|
+
* memory usage (RubyProf::MEMORY)
|
312
|
+
* garbage collections runs (RubyProf::GC_RUNS)
|
313
|
+
* garbage collection time (RubyProf::GC_TIME)
|
314
|
+
|
315
|
+
Process time measures the time used by a process between any two moments.
|
316
|
+
It is unaffected by other processes concurrently running
|
317
|
+
on the system. Note that Windows does not support measuring process
|
318
|
+
times - therefore, measurements on Windows defaults to wall time.
|
319
|
+
|
320
|
+
Wall time measures the real-world time elapsed between any two moments.
|
321
|
+
If there are other processes concurrently running on the system
|
322
|
+
that use significant CPU or disk time during a profiling run
|
323
|
+
then the reported results will be too large.
|
324
|
+
|
325
|
+
CPU time uses the CPU clock counter to measure time. The returned
|
326
|
+
values are dependent on the correctly setting the CPU's frequency.
|
327
|
+
This mode is only supported on Pentium or PowerPC platforms (linux only).
|
328
|
+
|
329
|
+
Object allocation reports show how many objects each method in
|
330
|
+
a program allocates. This support was added by Sylvain Joyeux
|
331
|
+
and requires a patched Ruby interpreter. For more information and
|
332
|
+
the patch, please see:
|
333
|
+
http://rubyforge.org/tracker/index.php?func=detail&aid=11497&group_id=426&atid=1700
|
334
|
+
|
335
|
+
Memory usage reports show how much memory each method in a program
|
336
|
+
uses. This support was added by Alexander Dymo and requires a
|
337
|
+
patched Ruby interpreter. For more information, see:
|
338
|
+
http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062
|
339
|
+
|
340
|
+
Garbage collection runs report how many times Ruby's garbage collector
|
341
|
+
is invoked during a profiling session. This support was added by Jeremy
|
342
|
+
Kemper and requires a patched Ruby interpreter. For more information, see:
|
343
|
+
http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062
|
344
|
+
|
345
|
+
Garbage collection time reports how much time is spent in Ruby's garbage collector
|
346
|
+
during a profiling session. This support was added by Jeremy Kemper
|
347
|
+
and requires a patched Ruby interpreter. For more information, see:
|
348
|
+
http://rubyforge.org/tracker/index.php?func=detail&aid=17676&group_id=1814&atid=7062
|
349
|
+
|
350
|
+
To set the measurement:
|
351
|
+
|
352
|
+
* RubyProf.measure_mode = RubyProf::PROCESS_TIME
|
353
|
+
* RubyProf.measure_mode = RubyProf::WALL_TIME
|
354
|
+
* RubyProf.measure_mode = RubyProf::CPU_TIME
|
355
|
+
* RubyProf.measure_mode = RubyProf::ALLOCATIONS
|
356
|
+
* RubyProf.measure_mode = RubyProf::MEMORY
|
357
|
+
* RubyProf.measure_mode = RubyProf::GC_RUNS
|
358
|
+
* RubyProf.measure_mode = RubyProf::GC_TIME
|
359
|
+
|
360
|
+
The default value is RubyProf::PROCESS_TIME.
|
361
|
+
|
362
|
+
You may also specify the measure_mode by using the RUBY_PROF_MEASURE_MODE
|
363
|
+
environment variable:
|
364
|
+
|
365
|
+
* export RUBY_PROF_MEASURE_MODE=process
|
366
|
+
* export RUBY_PROF_MEASURE_MODE=wall
|
367
|
+
* export RUBY_PROF_MEASURE_MODE=cpu
|
368
|
+
* export RUBY_PROF_MEASURE_MODE=allocations
|
369
|
+
* export RUBY_PROF_MEASURE_MODE=memory
|
370
|
+
* export RUBY_PROF_MEASURE_MODE=gc_runs
|
371
|
+
* export RUBY_PROF_MEASURE_MODE=gc_time
|
372
|
+
|
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
|
376
|
+
by the C runtime library. Note that the clock method does not
|
377
|
+
report time spent in the kernel or child processes and therefore
|
378
|
+
does not measure time spent in methods such as Kernel.sleep method.
|
379
|
+
If you need to measure these values, then use wall time. Wall time
|
380
|
+
is measured using the gettimeofday kernel method.
|
381
|
+
|
382
|
+
On Windows, timings default to wall times. If you set the clock
|
383
|
+
mode to PROCESS_TIME, then timing are read using the clock method
|
384
|
+
provided by the C runtime library. Note though, these values are
|
385
|
+
wall times on Windows and not process times like on Linux.
|
386
|
+
Wall time is measured using the GetLocalTime API.
|
387
|
+
|
388
|
+
If you use wall time, the results will be affected by other
|
389
|
+
processes running on your computer, network delays, disk access,
|
390
|
+
etc. As result, for the best results, try to make sure your
|
391
|
+
computer is only performing your profiling run and is
|
392
|
+
otherwise quiescent.
|
393
|
+
|
394
|
+
On both platforms, cpu time is measured using the RDTSC assembly
|
395
|
+
function provided by the Pentium and PowerPC platforms. CPU time
|
396
|
+
is dependent on the cpu's frequency. On Linux, ruby-prof attempts
|
397
|
+
to read this value from "/proc/cpuinfo." On Windows, you must
|
398
|
+
manually specify the clock frequency. This can be done using the
|
399
|
+
RUBY_PROF_CPU_FREQUENCY environment variable:
|
400
|
+
|
401
|
+
export RUBY_PROF_CPU_FREQUENCY=<value>
|
402
|
+
|
403
|
+
You can also directly set the cpu frequency by calling:
|
404
|
+
|
405
|
+
RubyProf.cpu_frequency = <value>
|
406
|
+
|
407
|
+
|
408
|
+
== Multi-threaded Applications
|
409
|
+
|
410
|
+
Unfortunately, Ruby does not provide an internal api
|
411
|
+
for detecting thread context switches in 1.8. As a result, the
|
412
|
+
timings ruby-prof reports for each thread may be slightly
|
413
|
+
inaccurate. In particular, this will happen for newly
|
414
|
+
spawned threads that go to sleep immediately (their first call).
|
415
|
+
For instance, if you use Ruby's timeout library to wait for 2 seconds,
|
416
|
+
the 2 seconds will be assigned to the foreground thread
|
417
|
+
and not the newly created background thread. These errors
|
418
|
+
can largely be avoided if the background thread performs any
|
419
|
+
operation before going to sleep.
|
420
|
+
|
421
|
+
== Performance
|
422
|
+
|
423
|
+
Significant effort has been put into reducing ruby-prof's overhead
|
424
|
+
as much as possible. Our tests show that the overhead associated
|
425
|
+
with profiling code varies considerably with the code being
|
426
|
+
profiled. Most programs will run approximately twice as slow
|
427
|
+
while highly recursive programs (like the fibonacci series test)
|
428
|
+
will run three times slower.
|
429
|
+
|
430
|
+
Because of some threading difficulties in 1.9, it currently runs a bit slower there.
|
431
|
+
http://www.ruby-forum.com/topic/201329
|
432
|
+
|
433
|
+
== License
|
434
|
+
|
435
|
+
See LICENSE for license information.
|
436
|
+
|
437
|
+
== Development
|
438
|
+
|
439
|
+
Code is located at http://github.com/rdp/ruby-prof
|