acunote-ruby-prof 0.9.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (84) hide show
  1. data/CHANGES +240 -0
  2. data/LICENSE +23 -0
  3. data/README.rdoc +439 -0
  4. data/Rakefile +148 -0
  5. data/bin/ruby-prof +236 -0
  6. data/examples/empty.png +0 -0
  7. data/examples/flat.txt +55 -0
  8. data/examples/graph.dot +106 -0
  9. data/examples/graph.html +823 -0
  10. data/examples/graph.png +0 -0
  11. data/examples/graph.txt +170 -0
  12. data/examples/minus.png +0 -0
  13. data/examples/multi.flat.txt +23 -0
  14. data/examples/multi.graph.html +906 -0
  15. data/examples/multi.grind.dat +194 -0
  16. data/examples/multi.stack.html +573 -0
  17. data/examples/plus.png +0 -0
  18. data/examples/stack.html +573 -0
  19. data/ext/ruby_prof/extconf.rb +43 -0
  20. data/ext/ruby_prof/measure_allocations.h +58 -0
  21. data/ext/ruby_prof/measure_cpu_time.h +152 -0
  22. data/ext/ruby_prof/measure_gc_runs.h +76 -0
  23. data/ext/ruby_prof/measure_gc_time.h +57 -0
  24. data/ext/ruby_prof/measure_memory.h +101 -0
  25. data/ext/ruby_prof/measure_process_time.h +52 -0
  26. data/ext/ruby_prof/measure_wall_time.h +53 -0
  27. data/ext/ruby_prof/mingw/Rakefile +23 -0
  28. data/ext/ruby_prof/mingw/build.rake +38 -0
  29. data/ext/ruby_prof/ruby_prof.c +1834 -0
  30. data/ext/ruby_prof/ruby_prof.h +190 -0
  31. data/ext/ruby_prof/version.h +4 -0
  32. data/lib/ruby-prof.rb +62 -0
  33. data/lib/ruby-prof/abstract_printer.rb +41 -0
  34. data/lib/ruby-prof/aggregate_call_info.rb +68 -0
  35. data/lib/ruby-prof/call_info.rb +112 -0
  36. data/lib/ruby-prof/call_stack_printer.rb +751 -0
  37. data/lib/ruby-prof/call_tree_printer.rb +133 -0
  38. data/lib/ruby-prof/dot_printer.rb +153 -0
  39. data/lib/ruby-prof/empty.png +0 -0
  40. data/lib/ruby-prof/flat_printer.rb +78 -0
  41. data/lib/ruby-prof/flat_printer_with_line_numbers.rb +72 -0
  42. data/lib/ruby-prof/graph_html_printer.rb +278 -0
  43. data/lib/ruby-prof/graph_printer.rb +245 -0
  44. data/lib/ruby-prof/method_info.rb +131 -0
  45. data/lib/ruby-prof/minus.png +0 -0
  46. data/lib/ruby-prof/multi_printer.rb +54 -0
  47. data/lib/ruby-prof/plus.png +0 -0
  48. data/lib/ruby-prof/rack.rb +30 -0
  49. data/lib/ruby-prof/result.rb +70 -0
  50. data/lib/ruby-prof/symbol_to_proc.rb +8 -0
  51. data/lib/ruby-prof/task.rb +146 -0
  52. data/lib/ruby-prof/test.rb +148 -0
  53. data/lib/unprof.rb +8 -0
  54. data/rails/environment/profile.rb +24 -0
  55. data/rails/example/example_test.rb +9 -0
  56. data/rails/profile_test_helper.rb +21 -0
  57. data/test/aggregate_test.rb +136 -0
  58. data/test/basic_test.rb +290 -0
  59. data/test/current_failures_windows +8 -0
  60. data/test/do_nothing.rb +0 -0
  61. data/test/duplicate_names_test.rb +32 -0
  62. data/test/enumerable_test.rb +16 -0
  63. data/test/exceptions_test.rb +15 -0
  64. data/test/exclude_threads_test.rb +54 -0
  65. data/test/exec_test.rb +14 -0
  66. data/test/line_number_test.rb +73 -0
  67. data/test/measurement_test.rb +122 -0
  68. data/test/method_elimination_test.rb +74 -0
  69. data/test/module_test.rb +44 -0
  70. data/test/multi_printer_test.rb +81 -0
  71. data/test/no_method_class_test.rb +13 -0
  72. data/test/prime.rb +55 -0
  73. data/test/prime_test.rb +13 -0
  74. data/test/printers_test.rb +164 -0
  75. data/test/recursive_test.rb +236 -0
  76. data/test/ruby-prof-bin +20 -0
  77. data/test/singleton_test.rb +38 -0
  78. data/test/stack_printer_test.rb +74 -0
  79. data/test/stack_test.rb +138 -0
  80. data/test/start_stop_test.rb +112 -0
  81. data/test/test_suite.rb +32 -0
  82. data/test/thread_test.rb +173 -0
  83. data/test/unique_call_path_test.rb +225 -0
  84. 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.
@@ -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