1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
|
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>README - ruby-prof</title>
<script type="text/javascript">
var rdoc_rel_prefix = "./";
var index_rel_prefix = "./";
</script>
<script src="./js/jquery.js"></script>
<script src="./js/darkfish.js"></script>
<link href="./css/fonts.css" rel="stylesheet">
<link href="./css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="file">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="./index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="./table_of_contents.html#pages">Pages</a>
<a href="./table_of_contents.html#classes">Classes</a>
<a href="./table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div class="nav-section">
<h3>Table of Contents</h3>
<ul class="link-list" role="directory">
<li><a href="#label-ruby-prof">ruby-prof</a>
<li><a href="#label-Overview">Overview</a>
<li><a href="#label-Requirements">Requirements</a>
<li><a href="#label-Install">Install</a>
<li><a href="#label-Usage">Usage</a>
<li><a href="#label-ruby-prof+Executable">ruby-prof Executable</a>
<li><a href="#label-ruby-prof+Convenience+API">ruby-prof Convenience API</a>
<li><a href="#label-Profiling+Selected+Threads+-28Core+API-29">Profiling Selected Threads (Core API)</a>
<li><a href="#label-Method+Elimination+-28Deprecated-29">Method Elimination (Deprecated)</a>
<li><a href="#label-Method+Exclusion">Method Exclusion</a>
<li><a href="#label-Profiling+Rails">Profiling Rails</a>
<li><a href="#label-Reports">Reports</a>
<li><a href="#label-Printers">Printers</a>
<li><a href="#label-Measurements">Measurements</a>
<li><a href="#label-Patching+ruby">Patching ruby</a>
<li><a href="#label-Measure+modes">Measure modes</a>
<li><a href="#label-Multi-threaded+Applications">Multi-threaded Applications</a>
<li><a href="#label-Performance">Performance</a>
<li><a href="#label-Editing+links">Editing links</a>
<li><a href="#label-License">License</a>
<li><a href="#label-API+Documentation">API Documentation</a>
<li><a href="#label-Development">Development</a>
</ul>
</div>
<div id="project-metadata">
<div id="fileindex-section" class="nav-section">
<h3>Pages</h3>
<ul class="link-list">
<li><a href="./LICENSE.html">LICENSE</a>
<li><a href="./README_rdoc.html">README</a>
<li><a href="./examples/flat_txt.html">flat</a>
<li><a href="./examples/graph_html.html">graph.html</a>
<li><a href="./examples/graph_txt.html">graph</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-label="Page README.rdoc">
<h1 id="label-ruby-prof">ruby-prof<span><a href="#label-ruby-prof">¶</a> <a href="#top">↑</a></span></h1>
<p><a href="https://travis-ci.org/ruby-prof/ruby-prof"><img
src="https://travis-ci.org/ruby-prof/ruby-prof.png?branch=master"
alt="Build Status" /></a></p>
<h2 id="label-Overview">Overview<span><a href="#label-Overview">¶</a> <a href="#top">↑</a></span></h2>
<p>ruby-prof is a fast code profiler for MRI Ruby. Its features include:</p>
<ul><li>
<p>Speed - it is a C extension and therefore many times faster than the
standard Ruby profiler.</p>
</li><li>
<p>Modes - Ruby prof can measure a number of different parameters, including
call times, memory usage and object allocations.</p>
</li><li>
<p>Reports - can generate text and cross-referenced html reports</p>
<ul><li>
<p>Flat Profiles - similar to the reports generated by the standard Ruby
profiler</p>
</li><li>
<p>Graph profiles - similar to GProf, these show how long a method runs, which
methods call it and which methods it calls.</p>
</li><li>
<p>Call tree profiles - outputs results in the calltree format suitable for
the KCacheGrind profiling tool.</p>
</li><li>
<p>Many more – see reports section of this README.</p>
</li></ul>
</li><li>
<p>Threads - supports profiling multiple threads simultaneously</p>
</li></ul>
<h2 id="label-Requirements">Requirements<span><a href="#label-Requirements">¶</a> <a href="#top">↑</a></span></h2>
<p>ruby-prof requires Ruby 1.9.3 or higher. Please note some ruby releases
have known bugs which cause ruby-prof problems, like incorrect
measurements. We suggest to use the latest minor patch level release if
possible. In particular, on the 2.1 branch of ruby you should use at least
2.1.7.</p>
<p>If you are running Linux or Unix you'll need a C compiler so the
extension can be compiled when it is installed.</p>
<p>If you are running Windows, then you may need to install the Windows
specific RubyGem which includes an already built extension (see Install
section).</p>
<h2 id="label-Install">Install<span><a href="#label-Install">¶</a> <a href="#top">↑</a></span></h2>
<p>The easiest way to install ruby-prof is by using Ruby Gems. To install:</p>
<pre class="ruby"><span class="ruby-identifier">gem</span> <span class="ruby-identifier">install</span> <span class="ruby-identifier">ruby</span><span class="ruby-operator">-</span><span class="ruby-identifier">prof</span>
</pre>
<p>If you're on windows then please install the devkit first so that it
can compile.</p>
<h2 id="label-Usage">Usage<span><a href="#label-Usage">¶</a> <a href="#top">↑</a></span></h2>
<p>There are three major options for running ruby-prof: via the command line,
via its convenience API or via its core API.</p>
<h3 id="label-ruby-prof+Executable">ruby-prof Executable<span><a href="#label-ruby-prof+Executable">¶</a> <a href="#top">↑</a></span></h3>
<p>The first is to use ruby-prof to run the Ruby program you want to profile.
For more information refer to the documentation of the ruby-prof command:
`$ ruby-prof -h.`</p>
<h3 id="label-ruby-prof+Convenience+API">ruby-prof Convenience API<span><a href="#label-ruby-prof+Convenience+API">¶</a> <a href="#top">↑</a></span></h3>
<p>The second way is to use the ruby-prof convenience API to profile
particular segments of code.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'ruby-prof'</span>
<span class="ruby-comment"># profile the code</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">start</span>
<span class="ruby-comment"># ... code to profile ...</span>
<span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
<span class="ruby-comment"># print a flat profile to text</span>
<span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">FlatPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
<span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(<span class="ruby-constant">STDOUT</span>)
</pre>
<p>Alternatively, you can use a block to tell ruby-prof what to profile:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'ruby-prof'</span>
<span class="ruby-comment"># profile the code</span>
<span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">profile</span> <span class="ruby-keyword">do</span>
<span class="ruby-comment"># ... code to profile ...</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># print a graph profile to text</span>
<span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">GraphPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
<span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(<span class="ruby-constant">STDOUT</span>, {})
</pre>
<p>ruby-prof also supports pausing and resuming profiling runs.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'ruby-prof'</span>
<span class="ruby-comment"># profile the code</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">start</span>
<span class="ruby-comment"># ... code to profile ...</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">pause</span>
<span class="ruby-comment"># ... other code ...</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">resume</span>
<span class="ruby-comment"># ... code to profile ...</span>
<span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
</pre>
<p>Note that resume will only work if start has been called previously. In
addition, resume can also take a block:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'ruby-prof'</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">resume</span> <span class="ruby-keyword">do</span>
<span class="ruby-comment"># ... code to profile...</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
</pre>
<p>With this usage, resume will automatically call pause at the end of the
block.</p>
<h3 id="label-Profiling+Selected+Threads+-28Core+API-29">Profiling Selected Threads (Core API)<span><a href="#label-Profiling+Selected+Threads+-28Core+API-29">¶</a> <a href="#top">↑</a></span></h3>
<p>The convenience API does not support running multiple profiles in separate
threads concurrently, but the <a
href="RubyProf/Profile.html">RubyProf::Profile</a> API does. In fact, the
convenience layer uses the Profile API internally. It all revolves around
Profile objects:</p>
<dl class="rdoc-list note-list"><dt><a href="RubyProf/Profile.html#method-c-new">RubyProf::Profile.new</a>
<dd>
<p>Create a profile object given an options hash (see below)</p>
<p>The following options are available when creating Profile instances:</p>
<dl class="rdoc-list note-list"><dt>measure_mode
<dd>
<p>One of the defined measure modes</p>
</dd><dt>exclude_threads
<dd>
<p>Array of threads which should not be profiled.</p>
</dd><dt>include_threads
<dd>
<p>Array of threads which should be profiled. All other threads will be
ignored.</p>
</dd><dt>merge_fibers
<dd>
<p>Whether profiling data for a given thread's fibers should all be
subsumed under a single entry. Basically only useful to produce callgrind
profiles.</p>
</dd></dl>
</dd><dt><a href="RubyProf/Profile.html#method-i-start">RubyProf::Profile#start</a>
<dd>
<p>Start profiling</p>
</dd><dt><a href="RubyProf/Profile.html#method-i-pause">RubyProf::Profile#pause</a>
<dd>
<p>Pause profiling</p>
</dd><dt><a href="RubyProf/Profile.html#method-i-resume">RubyProf::Profile#resume</a>
<dd>
<p>Resume profiling</p>
</dd><dt><a href="RubyProf/Profile.html#method-i-stop">RubyProf::Profile#stop</a>
<dd>
<p>Stop profiling and return self</p>
</dd><dt><a href="RubyProf/Profile.html#method-i-profile">RubyProf::Profile#profile</a>
<dd>
<p>Perform a profile run and return result. Accepts the same arguments as <a
href="RubyProf/Profile.html#method-c-new">RubyProf::Profile.new</a>.</p>
</dd></dl>
<h2 id="label-Method+Elimination+-28Deprecated-29">Method Elimination (Deprecated)<span><a href="#label-Method+Elimination+-28Deprecated-29">¶</a> <a href="#top">↑</a></span></h2>
<p>ruby-prof supports eliminating specific methods and threads from profiling
results. This is useful for reducing connectivity in the call graph, making
it easier to identify the source of performance problems when using a graph
printer.</p>
<p>For example, consider <code>Integer#times</code>: it's hardly ever
useful to know how much time is spent in the method itself. We're much
more interested in how much the passed in block contributes to the time
spent in the method which contains the <code>Integer#times</code> call.</p>
<p>Methods are eliminated from the collected data by calling
<code>eliminate_methods!</code> on the profiling result, before submitting
it to a printer.</p>
<pre class="ruby"><span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
<span class="ruby-identifier">result</span>.<span class="ruby-identifier">eliminate_methods!</span>([<span class="ruby-node">/Integer#times/</span>])
</pre>
<p>The argument given to <code>eliminate_methods!</code> is either an array of
regular expressions, or the name of a file containing a list of regular
expressions (line separated text).</p>
<p>After eliminating methods the resulting profile will appear exactly as if
those methods had been inlined at their call sites.</p>
<h2 id="label-Method+Exclusion">Method Exclusion<span><a href="#label-Method+Exclusion">¶</a> <a href="#top">↑</a></span></h2>
<p>ruby-prof supports exluding methods from profiling. The effect on collected
metrics are identical to eliminating methods from the profiling result in a
prost process step. The interface is slightly different though:</p>
<pre>profile = RubyProf.new(...)
profile.exclude_methods!(Integer, :times, ...)
profile.start</pre>
<p>A convenience method is provided to exclude a large number of methods which
usually clutter up profiles:</p>
<pre class="ruby"><span class="ruby-identifier">profile</span>.<span class="ruby-identifier">exclude_common_methods!</span>
</pre>
<p>However, this is a somewhat opinionated method collection. It's usually
better to view it as an inspiration instead of using it directly (see <a
href="https://github.com/ruby-prof/ruby-prof/blob/e087b7d7ca11eecf1717d95a5c5fea1e36ea3136/lib/ruby-prof/profile/exclude_common_methods.rb">github.com/ruby-prof/ruby-prof/blob/e087b7d7ca11eecf1717d95a5c5fea1e36ea3136/lib/ruby-prof/profile/exclude_common_methods.rb</a>).</p>
<h2 id="label-Profiling+Rails">Profiling Rails<span><a href="#label-Profiling+Rails">¶</a> <a href="#top">↑</a></span></h2>
<p>To profile a Rails application it is vital to run it using production like
settings (cache classes, cache view lookups, etc.). Otherwise, Rail's
dependency loading code will overwhelm any time spent in the application
itself (our tests show that Rails dependency loading causes a roughly 6x
slowdown). The best way to do this is create a new Rails environment,
profile.rb.</p>
<p>So to profile Rails:</p>
<ol><li>
<p>Create a new profile.rb environment. Make sure to turn on
<code>cache_classes</code> and <code>cache_template_loading</code>.
Otherwise your profiling results will be overwhelmed by the time Rails
spends loading required files. You should likely turn off caching.</p>
</li><li>
<p>Add the ruby-prof to your gemfile:</p>
<pre class="ruby"><span class="ruby-identifier">group</span> :<span class="ruby-identifier">profile</span> <span class="ruby-keyword">do</span>
<span class="ruby-identifier">gem</span> <span class="ruby-string">'ruby-prof'</span>
<span class="ruby-keyword">end</span>
</pre>
</li><li>
<p>Add the ruby prof rack adapter to your middleware stack. One way to do
this is by adding the following code to <code>config.ru</code>:</p>
<pre class="ruby"><span class="ruby-keyword">if</span> <span class="ruby-constant">Rails</span>.<span class="ruby-identifier">env</span>.<span class="ruby-identifier">profile?</span>
<span class="ruby-identifier">use</span> <span class="ruby-constant">Rack</span><span class="ruby-operator">::</span><span class="ruby-constant">RubyProf</span>, :<span class="ruby-identifier">path</span> =<span class="ruby-operator">></span> <span class="ruby-string">'/temp/profile'</span>
<span class="ruby-keyword">end</span>
</pre>
<p>The path is where you want profiling results to be stored. By default the
rack adapter will generate a html call graph report and flat text report.</p>
</li><li>
<p>Now make a request to your running server. New profiling information will
be generated for each request. Note that each request will overwrite the
profiling reports created by the previous request!</p>
</li></ol>
<h2 id="label-Reports">Reports<span><a href="#label-Reports">¶</a> <a href="#top">↑</a></span></h2>
<p>ruby-prof can generate a number of different reports:</p>
<ul><li>
<p>Flat Reports</p>
</li><li>
<p>Graph Reports</p>
</li><li>
<p>HTML Graph Reports</p>
</li><li>
<p>Call graphs</p>
</li><li>
<p>Call stack reports</p>
</li><li>
<p>More!</p>
</li></ul>
<p>Flat profiles show the overall time spent in each method. They are a good
way of quickly identifying which methods take the most time. An example of
a flat profile and an explanation can be found in <a
href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/flat.txt">examples/flat.txt</a>.</p>
<p>There are several varieties of these - run <code>ruby-prof --help</code></p>
<p>Graph profiles also show the overall time spent in each method. In
addition, they also show which methods call the current method and which
methods its calls. Thus they are good for understanding how methods gets
called and provide insight into the flow of your program. An example text
graph profile is located at <a
href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.txt">examples/graph.txt</a>.</p>
<p>HTML Graph profiles are the same as graph profiles, except output is
generated in hyper-linked HTML. Since graph profiles can be quite large,
the embedded links make it much easier to navigate the results. An example
html graph profile is located at <a
href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.html">examples/graph.html</a>.</p>
<p>Call graphs output results in the calltree profile format which is used by
KCachegrind. Call graph support was generously donated by Carl Shimer. More
information about the format can be found at the <a
href="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat">KCachegrind</a>
site.</p>
<p>Call stack reports produce a HTML visualization of the time spent in each
execution path of the profiled code. An example can be found at <a
href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/stack.html">examples/stack.html</a>.</p>
<p>Another good example: <a
href="http://twitpic.com/28z94a">twitpic.com/28z94a</a></p>
<p>Finally, there's a so called MultiPrinter which can generate several
reports in one profiling run. See <a
href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/multi.stack.html">examples/multi.stack.html</a>.</p>
<p>There is also a graphviz .dot visualiser.</p>
<h2 id="label-Printers">Printers<span><a href="#label-Printers">¶</a> <a href="#top">↑</a></span></h2>
<p>Reports are created by printers. Supported printers include:</p>
<dl class="rdoc-list note-list"><dt><a href="RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a>
<dd>
<p>Creates a flat report in text format</p>
</dd><dt><a href="RubyProf/FlatPrinterWithLineNumbers.html">RubyProf::FlatPrinterWithLineNumbers</a>
<dd>
<p>Same as above but more verbose</p>
</dd><dt><a href="RubyProf/GraphPrinter.html">RubyProf::GraphPrinter</a>
<dd>
<p>Creates a call graph report in text format</p>
</dd><dt><a href="RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a>
<dd>
<p>Creates a call graph report in HTML (separate files per thread)</p>
</dd><dt><a href="RubyProf/DotPrinter.html">RubyProf::DotPrinter</a>
<dd>
<p>Creates a call graph report in GraphViz's DOT format which can be
converted to an image</p>
</dd><dt><a href="RubyProf/CallTreePrinter.html">RubyProf::CallTreePrinter</a>
<dd>
<p>Creates a call tree report compatible with KCachegrind</p>
</dd><dt><a href="RubyProf/CallStackPrinter.html">RubyProf::CallStackPrinter</a>
<dd>
<p>Creates a HTML visualization of the Ruby stack</p>
</dd><dt><a href="RubyProf/MultiPrinter.html">RubyProf::MultiPrinter</a>
<dd>
<p>Uses the other printers to create several reports in one profiling run</p>
</dd></dl>
<p>Most printers are used in the following way:</p>
<pre class="ruby"><span class="ruby-identifier">result</span> = <span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">stop</span>
<span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">GraphPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
<span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(<span class="ruby-constant">STDOUT</span>, :<span class="ruby-identifier">min_percent</span> =<span class="ruby-operator">></span> <span class="ruby-value">2</span>)
</pre>
<p>The first parameter is any writable IO object such as <code>STDOUT</code>
or a file. The second parameter, specifies the minimum percentage a method
must take to be printed. Percentages should be specified as integers in
the range 0 to 100. For more information please see the documentation for
the different printers.</p>
<p>The other option is <code>:print_file => true</code> (default false),
which adds the filename to the output (GraphPrinter only).</p>
<p><code>MultiPrinter</code> and <code>CallTreePrinter</code>differ from the
other printers in that they require a directory path and a profile basename
for the files they produce:</p>
<pre class="ruby"><span class="ruby-identifier">printer</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">MultiPrinter</span>.<span class="ruby-identifier">new</span>(<span class="ruby-identifier">result</span>)
<span class="ruby-identifier">printer</span>.<span class="ruby-identifier">print</span>(:<span class="ruby-identifier">path</span> =<span class="ruby-operator">></span> <span class="ruby-string">"."</span>, :<span class="ruby-identifier">profile</span> =<span class="ruby-operator">></span> <span class="ruby-string">"profile"</span>)
</pre>
<p>The values given in the example above are the defaults.</p>
<h2 id="label-Measurements">Measurements<span><a href="#label-Measurements">¶</a> <a href="#top">↑</a></span></h2>
<p>Depending on the mode and platform, ruby-prof can measure various aspects
of a Ruby program. Supported measurements include:</p>
<dl class="rdoc-list note-list"><dt>RubyProf::WALL_TIME
<dd>
<p>Wall time measures the real-world time elapsed between any two moments. If
there are other processes concurrently running on the system that use
significant CPU or disk time during a profiling run then the reported
results will be larger than expected.</p>
</dd><dt>RubyProf::PROCESS_TIME
<dd>
<p>Process time measures the time used by a process between any two moments.
It is unaffected by other processes concurrently running on the system.
Note that Windows does not support measuring process times.</p>
</dd><dt>RubyProf::CPU_TIME
<dd>
<p>CPU time uses the CPU clock counter to measure time. The returned values
are dependent on the correctly setting the CPU's frequency. This mode
is only supported on Pentium or PowerPC platforms (linux only).</p>
</dd><dt>RubyProf::ALLOCATIONS
<dd>
<p>Object allocation reports show how many objects each method in a program
allocates. This support was added by Sylvain Joyeux and requires a patched
Ruby interpreter. See below.</p>
</dd><dt>RubyProf::MEMORY
<dd>
<p>Memory usage reports show how much memory each method in a program uses.
This support was added by Alexander Dymo and requires a patched Ruby
interpreter. See below.</p>
</dd><dt>RubyProf::GC_TIME
<dd>
<p>Garbage collection time reports how much time is spent in Ruby's
garbage collector during a profiling session. This support was added by
Jeremy Kemper and requires a patched Ruby interpreter. See below.</p>
</dd><dt>RubyProf::GC_RUNS
<dd>
<p>Garbage collection runs report how many times Ruby's garbage collector
is invoked during a profiling session. This support was added by Jeremy
Kemper and requires a patched Ruby interpreter. See below.</p>
</dd></dl>
<h2 id="label-Patching+ruby">Patching ruby<span><a href="#label-Patching+ruby">¶</a> <a href="#top">↑</a></span></h2>
<p>All of the patches to Ruby are included in the railsexpress patchsets for
rvm, see <a
href="https://github.com/skaes/rvm-patchsets">github.com/skaes/rvm-patchsets</a>.
You can also use these patches manually with other ruby managers
(ruby-install, ruby-build, etc.).</p>
<p>Note if you rebuild your ruby with patches you must uninstall and reinstall
the ruby-prof gem to take advantage of the new capabilities.</p>
<h2 id="label-Measure+modes">Measure modes<span><a href="#label-Measure+modes">¶</a> <a href="#top">↑</a></span></h2>
<p>To set the measurement:</p>
<pre class="ruby"><span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">WALL_TIME</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">PROCESS_TIME</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">CPU_TIME</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">ALLOCATIONS</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">MEMORY</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">GC_TIME</span>
<span class="ruby-constant">RubyProf</span>.<span class="ruby-identifier">measure_mode</span> = <span class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span class="ruby-constant">GC_RUNS</span>
</pre>
<p>The default value is <code>RubyProf::WALL_TIME</code>.</p>
<p>You may also specify the measure mode by using the
<code>RUBY_PROF_MEASURE_MODE</code> environment variable:</p>
<pre class="ruby"><span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">wall</span>
<span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">process</span>
<span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">cpu</span>
<span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">allocations</span>
<span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">memory</span>
<span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">gc_time</span>
<span class="ruby-identifier">export</span> <span class="ruby-constant">RUBY_PROF_MEASURE_MODE</span>=<span class="ruby-identifier">gc_runs</span>
</pre>
<p>On Linux, process time is measured using the clock method provided by the C
runtime library. Note that the clock method does not report time spent in
the kernel or child processes and therefore does not measure time spent in
methods such as Kernel.sleep method. If you need to measure these values,
then use wall time. Wall time is measured using the gettimeofday kernel
method.</p>
<p>If you set the clock mode to <code>PROCESS_TIME</code>, then timings are
read using the clock method provided by the C runtime library. Note
though, these values are wall times on Windows and not process times like
on Linux. Wall time is measured using the GetLocalTime API.</p>
<p>If you use wall time, the results will be affected by other processes
running on your computer, network delays, disk access, etc. As result, for
the best results, try to make sure your computer is only performing your
profiling run and is otherwise quiescent.</p>
<h2 id="label-Multi-threaded+Applications">Multi-threaded Applications<span><a href="#label-Multi-threaded+Applications">¶</a> <a href="#top">↑</a></span></h2>
<p>Unfortunately, Ruby does not provide an internal API for detecting thread
context switches. As a result, the timings ruby-prof reports for each
thread may be slightly inaccurate. In particular, this will happen for
newly spawned threads that go to sleep immediately (their first call). For
instance, if you use Ruby's timeout library to wait for 2 seconds, the
2 seconds will be assigned to the foreground thread and not the newly
created background thread. These errors can largely be avoided if the
background thread performs any operation before going to sleep.</p>
<h2 id="label-Performance">Performance<span><a href="#label-Performance">¶</a> <a href="#top">↑</a></span></h2>
<p>Significant effort has been put into reducing ruby-prof's overhead as
much as possible. Our tests show that the overhead associated with
profiling code varies considerably with the code being profiled. Most
programs will run approximately twice as slow while highly recursive
programs (like the fibonacci series test) will run three times slower.</p>
<h2 id="label-Editing+links">Editing links<span><a href="#label-Editing+links">¶</a> <a href="#top">↑</a></span></h2>
<p>Use <code>RUBY_PROF_EDITOR_URI</code> environment variable to open source
code files in your favorite text editor. For example,
<code>RUBY_PROF_EDITOR_URI=atm</code> will produce links for Atom text
editor.</p>
<h2 id="label-License">License<span><a href="#label-License">¶</a> <a href="#top">↑</a></span></h2>
<p>See <a href="LICENSE.html">LICENSE</a> for license information.</p>
<h2 id="label-API+Documentation">API Documentation<span><a href="#label-API+Documentation">¶</a> <a href="#top">↑</a></span></h2>
<p>The ruby-prof API documentation for the latest released gem version can be
found here: <a
href="http://www.rubydoc.info/gems/ruby-prof">www.rubydoc.info/gems/ruby-prof</a>/</p>
<p>The ruby-prof API documentation for the master branch is available here: <a
href="http://www.rubydoc.info/github/ruby-prof/ruby-prof">www.rubydoc.info/github/ruby-prof/ruby-prof</a>/</p>
<h2 id="label-Development">Development<span><a href="#label-Development">¶</a> <a href="#top">↑</a></span></h2>
<p>Code is located at <a
href="https://github.com/ruby-prof/ruby-prof">github.com/ruby-prof/ruby-prof</a></p>
<p>Google group/mailing list: <a
href="http://groups.google.com/group/ruby-optimization">groups.google.com/group/ruby-optimization</a>
or open a github issue.</p>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="http://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://rdoc.github.io/rdoc">RDoc</a> 5.1.0.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>
|
