Skip to content

Commit 8980810

Browse files
author
Charlie Savage
committed
Specify measurement sizes.
1 parent bbda0e5 commit 8980810

File tree

1 file changed

+40
-66
lines changed

1 file changed

+40
-66
lines changed

‎index.html‎

Lines changed: 40 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -40,25 +40,9 @@ <h2><a id="overview">Overview</a></h2>
4040
process time, object allocations and memory usage</p>
4141
</li>
4242
<li>
43-
<p>Reports - ruby-prof can generate text and cross-referenced html
44-
reports</p>
43+
<p>Reports - ruby-prof can generate a variety of text and
44+
cross-referenced html reports</p>
4545
<ul>
46-
<li>
47-
<p>Flat Profiles - similar to the reports generated by the
48-
standard Ruby profiler</p>
49-
</li>
50-
<li>
51-
<p>Graph profiles - similar to GProf, these show how long a
52-
method runs, which methods call it and which methods it calls.</p>
53-
</li>
54-
<li>
55-
<p>Call tree profiles - outputs results in the calltree format
56-
suitable for the KCacheGrind profiling tool.</p>
57-
</li>
58-
<li>
59-
<p>Many more – see <a href="#reports">reports </a>section of
60-
this README.</p>
61-
</li>
6246
</ul>
6347
</li>
6448
<li>
@@ -71,7 +55,7 @@ <h2><a id="why-ruby-prof">Why ruby-prof?</a></h2>
7155
large number of objects or allocate objects with high memory usage.
7256
Often times the results will be surprising - when profiling what you
7357
think you know almost always turns out to be wrong.</p>
74-
<p>Because ruby-prof is built using ruby's C <a href="https://ruby-doc.org/core-2.6.1/TracePoint.html">tracepoint
58+
<p>Since ruby-prof is built using ruby's C <a href="https://ruby-doc.org/core-2.6.1/TracePoint.html">tracepoint
7559
</a>api, it knows a lot about your program. However, using ruby-prof
7660
also comes with two caveats:</p>
7761
<ul>
@@ -82,7 +66,7 @@ <h2><a id="why-ruby-prof">Why ruby-prof?</a></h2>
8266
</li>
8367
<li>
8468
<p>Using ruby-prof will cause your program to run slower (see <a href="#performance">
85-
Performance </a>section) </p>
69+
Performance</a> section) </p>
8670
</li>
8771
</ul>
8872
<p>Most of the time, these two caveats are acceptable. But if you need
@@ -105,7 +89,7 @@ <h2><a id="installation">Installation</a></h2>
10589
<p>ruby-prof requires Ruby 2.4.0 or higher.</p>
10690
<p><strong>!!!WARNING!!!</strong> - The TracePoint api in Ruby versions
10791
2.6.1 through 2.6.3 has a <a href="https://bugs.ruby-lang.org/issues/15911">bug</a>
108-
that can cause ruby-prof to return incorrect results.</p>
92+
that can cause ruby-prof to return incorrect results. </p>
10993
<h2><a id="getting-started">Getting Started</a></h2>
11094
<p>There are three ways to use ruby-prof:</p>
11195
<ul>
@@ -118,7 +102,7 @@ <h3><a id="command-line">Command Line </a></h3>
118102
requires no modifications to your program.&nbsp; The basic usage is:</p>
119103
<pre>ruby-prof [options] &lt;script.rb&gt; [--] [script-options]<span style="color:#808080;font-weight:bold;font-style:italic;">"</span></pre>
120104
<p> Where script.rb is the program you want to profile.</p>
121-
<p>For a full list of options, see <a href="../doc/RubyProf/Cmd.html">RubyProf::Cmd</a>
105+
<p>For a full list of options, see <a href="doc/RubyProf/Cmd.html">RubyProf::Cmd</a>
122106
documentation or execute the following command:</p>
123107
<pre>ruby-prof -h</pre>
124108
<h3>Convenience API<span></span></h3>
@@ -197,31 +181,31 @@ <h3>Core API</h3>
197181
result = profile.profile do
198182
...
199183
end</pre>
200-
Once a profile is completed, you can either generate a <a href="#reports">report
184+
Once a profile is completed, you can either generate a <a href="#reports">report
201185
</a>via a printer or <a href="#saving-results">save</a> the results
202186
for later analysis. For a list of profiling options, please see the <a
203187
href="#profiling-options">Profiling Options</a> section.
204188
<h2><a id="advanced-usage">Advanced Usage</a></h2>
205189
<p>This section describes advanced usage of ruby-prof. Additional
206-
documentation for every class is also <a href="../doc/index.html">available</a>.</p>
190+
documentation for every class is also <a href="#api-documentation">available</a>.</p>
207191
<h3><a id="profiling-options">Profiling Options</a></h3>
208192
<p>ruby-prof understands the following options when profiling code:</p>
209193
<dl>
210194
<dt> measure_mode</dt>
211-
<dd>What ruby-prof should measure. For more information see the <a href="#measurements">Measurement
195+
<dd>What ruby-prof should measure. For more information see the <a href="#measurements">Measurement
212196
Mode</a> section. </dd>
213197
<dt>track_allocations</dt>
214198
<dd> Tracks each object location, including the object class, memory
215-
size and source file location. For more information see the <a href="#allocation-tracking">Allocation
199+
size and source file location. For more information see the <a href="#allocation-tracking">Allocation
216200
Tracking</a> section. </dd>
217201
<dt> exclude_threads</dt>
218202
<dd>Array of threads which should not be profiled. For more
219203
information see the <a href="#thread-inclusion-exclusion">Thread
220204
Inclusion/Exclusion</a> section. </dd>
221205
<dt> include_threads</dt>
222206
<dd>Array of threads which should be profiled. All other threads will
223-
be ignored. For more information see the <a href="#thread-inclusion-exclusion">Thread
224-
Inclusion/Exclusion</a> section.</dd>
207+
be ignored. For more information see the <a href="#thread-inclusion-exclusion">Thread
208+
Inclusion/Exclusion</a> section. </dd>
225209
</dl>
226210
<h3><a id="measurements">Measurement Mode<br <="" a="">
227211
</a></h3>
@@ -231,21 +215,21 @@ <h3><a id="measurements">Measurement Mode<br <="" a="">
231215
<dt>RubyProf::WALL_TIME</dt>
232216
<dd>
233217
<p>Wall time measures the real-world time elapsed between any two
234-
moments. If there are other processes concurrently running on the
235-
system that use significant CPU or disk time during a profiling
236-
run then the reported results will be larger than expected. On
237-
Windows, wall time is measured using <code>GetTickCount()</code>,
218+
moments in seconds. If there are other processes concurrently
219+
running on the system that use significant CPU or disk time during
220+
a profiling run then the reported results will be larger than
221+
expected. On Windows, wall time is measured using <code>GetTickCount()</code>,
238222
on MacOS by <code>mach_absolute_time</code>, on Linux by <code>clock_gettime</code>
239223
and otherwise by <code>gettimeofday</code>.</p>
240224
</dd>
241225
<dt>RubyProf::PROCESS_TIME</dt>
242226
<dd>
243227
<p>Process time measures the time used by a process between any two
244-
moments. It is unaffected by other processes concurrently running
245-
on the system. Remember with process time that calls to methods
246-
like sleep will not be included in profiling results. On Windows,
247-
process time is measured using <code>GetProcessTimes</code> and
248-
on other platforms by <code>clock_gettime</code>.</p>
228+
moments in seconds. It is unaffected by other processes
229+
concurrently running on the system. Remember with process time
230+
that calls to methods like sleep will not be included in profiling
231+
results. On Windows, process time is measured using <code>GetProcessTimes</code>
232+
and on other platforms by <code>clock_gettime</code>.</p>
249233
</dd>
250234
<dt>RubyProf::ALLOCATIONS</dt>
251235
<dd>
@@ -255,8 +239,8 @@ <h3><a id="measurements">Measurement Mode<br <="" a="">
255239
</dd>
256240
<dt>RubyProf::MEMORY</dt>
257241
<dd>
258-
<p>Memory measures how much memory each method in a program uses.
259-
Measurements are done via Ruby's<span style="font-family: monospace;">
242+
<p>Memory measures how much memory each method in a program uses in
243+
bytes. Measurements are done via Ruby's<span style="font-family: monospace;">
260244
TracePoint</span><code></code> api.</p>
261245
</dd>
262246
</dl>
@@ -299,7 +283,8 @@ <h3><a id="allocation-tracking">Allocation Tracking</a></h3>
299283
high level information about the number of allocations performed in
300284
each method. In contrast, tracking allocations provides detailed
301285
information about the type, number, memory usage and location of each
302-
allocation. Currently, to see allocations results you must use the <code>RubyProf::GraphHtmlPrinter</code>.</p>
286+
allocation. Currently, to see allocations results you must use the <a
287+
href="doc/RubyProf/GraphHtmlPrinter.html"><code>RubyProf::GraphHtmlPrinter</code></a>.</p>
303288
<a id="thread-inclusion-exclusion">
304289
<h3>Thread Inclusion/Exclusion</h3>
305290
<p>ruby-prof can profile multiple threads. Sometimes this can be
@@ -339,8 +324,8 @@ <h3><a id="method-exclusion">Method Exclusion</a></h3>
339324
</p>
340325
<h3><a id="saving-results">Saving Results</a></h3>
341326
<p>It can be helpful to save the results of a profiling run for later
342-
analysis.&nbsp; Results can be saved using Ruby's <a href="https://ruby-doc.org/core-2.6.3/Marshal.html">marshal
343-
</a>library.</p>
327+
analysis.&nbsp; Results can be saved using Ruby's <a href="https://ruby-doc.org/core-2.6.3/Marshal.html">marshal</a>
328+
library.</p>
344329
<pre>profile_1 = RubyProf.profile do
345330
...
346331
end
@@ -370,51 +355,45 @@ <h2><a id="reports">Reports</a></h2>
370355
documentation for the different printers.</p>
371356
<p>The different types of reports, and their associated printers, are:</p>
372357
<dl>
373-
<dt>Flat Report (RubyProf::FlatPrinter)</dt>
358+
<dt>Flat Report (<a href="doc/RubyProf/FlatPrinter.html">RubyProf::FlatPrinter</a>)</dt>
374359
<dd>The flat report show the overall time spent in each method. Its is
375360
a good way of quickly identifying which methods take the most time.
376361
An example of a flat report can be found in <a href="./examples/primes.flat.txt">examples/primes.flat.txt</a>.
377362
</dd>
378-
<dt>Flat Reports With Lines (RubyProf::FlatPrinterWithLineNumbers)</dt>
379-
<dd>The flat report with line numbers is similar to flat reports, but
380-
adds in addtional column showing the source of the profiled method.
381-
An example of a flat report with line numbers and an explanation can
382-
be found in <a href="./examples/primes.flat_with_lines.txt">examples/primes.flat_with_lines.txt</a>.
383-
</dd>
384-
<dt>Graph Reports (RubyProf::GraphPrinter)</dt>
363+
<dt>Graph Reports (<a href="doc/RubyProf/GraphHtmlPrinter.html">RubyProf::GraphPrinter</a>)</dt>
385364
<dd>The graph report shows the overall time spent in each method. In
386365
addition, it also show which methods call the current method and
387366
which methods its calls. Thus they are good for understanding how
388367
methods gets called and provide insight into the flow of your
389368
program. An example graph report is located at <a href="./examples/primes.graph.txt">examples/primes.graph.txt</a>.
390369
<br>
391370
</dd>
392-
<dt>HTML Graph Reports (RubyProf::GraphHtmlPrinter)</dt>
371+
<dt>HTML Graph Reports (<a href="doc/RubyProf/GraphHtmlPrinter.html">RubyProf::GraphHtmlPrinter</a>)</dt>
393372
<dd>HTML Graph profiles are the same as graph reports, except output
394373
is generated in hyper-linked HTML. Since graph reports can be quite
395374
large, the embedded links make it much easier to navigate the
396375
results. An example html graph profile is located at <a href="./examples/primes.graph.html">examples/primes.graph.html</a>.
397376
</dd>
398-
<dt>Call stack reports (RubyProf::CallStackPrinter)</dt>
377+
<dt>Call stack reports (<a href="doc/RubyProf/CallStackPrinter.html">RubyProf::CallStackPrinter</a>)</dt>
399378
<dd>Call stack reports produce a HTML visualization of the time spent
400379
in each execution path of the profiled code. An example can be found
401-
at <a href="http://github.com/ruby-prof/ruby-prof/tree/master/examples/stack.html">examples/stack.html</a>.
380+
at <a href="examples/primes.stack.html">examples/primes.stack.html</a>.
402381
</dd>
403-
<dt>Call graphs (RubyProf::CallTreePrinter)</dt>
382+
<dt>Call graphs (<a href="doc/RubyProf/CallTreePrinter.html">RubyProf::CallTreePrinter</a>)</dt>
404383
<dd>Call graphs output results in the calltree profile format which is
405384
used by KCachegrind. More information about the format can be found
406385
at the <a href="https://kcachegrind.github.io/html/Home.html">KCachegrind</a>
407-
site. An example can be found at <a href="./examples/primes.callgrind.out.24472">examples/primes.callgrind.out.24472</a>.
386+
site. An example can be found at <a href="examples/primes.callgrind.out.2540">examples/primes.callgrind.out.2540</a>.
408387
</dd>
409-
<dt>Graphviz reports (RubyProf::DotPrinter)</dt>
388+
<dt>Graphviz reports (<a href="doc/RubyProf/DotPrinter.html">RubyProf::DotPrinter</a>)</dt>
410389
<dd>The graphviz report is designed to be opened by <a href="https://www.graphviz.org/">Graphviz
411390
</a>to create visualization of profile results. An example can be
412391
found at <a href="./examples/primes.dot">examples/primes.dot</a>. </dd>
413-
<dt>Multiple reports (RubyProf::MultiPrinter)</dt>
392+
<dt>Multiple reports (<a href="doc/RubyProf/MultiPrinter.html">RubyProf::MultiPrinter</a>)</dt>
414393
<dd>MultiPrinter which can generate several reports in one profiling
415394
run. <code>MultiPrinter</code><span style="font-family: monospace;">
416395
</span>requires a directory path and a profile basename for the
417-
files they produce:
396+
files they produce
418397
<pre class="ruby"><span class="ruby-identifier">printer</span> = <span
419398
class="ruby-constant">RubyProf</span><span class="ruby-operator">::</span><span
420399
class="ruby-constant">MultiPrinter</span>.<span class="ruby-identifier">new</span>(<span
@@ -424,11 +403,6 @@ <h2><a id="reports">Reports</a></h2>
424403
class="ruby-value">:profile</span> <span class="ruby-operator">=&gt;</span> <span
425404
class="ruby-string">"profile"</span>)
426405
</pre> </dd>
427-
</dl>
428-
Use <code>RUBY_PROF_EDITOR_URI</code> environment variable to open
429-
source code files in your favorite text editor. For example, <code>RUBY_PROF_EDITOR_URI=atm</code>
430-
will produce links for Atom text editor.
431-
<dl class="rdoc-list note-list">
432406
</dl>
433407
<h2><a id="performance">Performance</a></h2>
434408
<p>Significant effort has been put into reducing ruby-prof's overhead.
@@ -508,7 +482,7 @@ <h2><a id="version-1.0">Version 1.0</a></h2>
508482
required.</p>
509483
</li>
510484
<li>
511-
<p>Remove support for method elimination (instead use <a href="#method-exclusion">method
485+
<p>Remove support for method elimination (instead use <a href="#method-exclusion">method
512486
exclusion</a>).</p>
513487
</li>
514488
<li>
@@ -522,10 +496,10 @@ <h2><a id="version-1.0">Version 1.0</a></h2>
522496
value (shout out if you want it back).</p>
523497
</li>
524498
<li>Merge the <code>RubyProf::FlatPrinterWithLineNumbers</code>
525-
printer into <code>RubyProf::FlatPrinter</code>.</li>
499+
printer into <code>RubyProf::FlatPrinter</code>. </li>
526500
<li>Removed support for RUBY_PROF_EDITOR_URI environment variable that
527501
specified the link scheme. This features was more confusing then
528-
helpful.</li>
502+
helpful. </li>
529503
</ul>
530504
<h2><a id="api-documentation">API Documentation</a></h2>
531505
<p>API documenation for each class is <a href="doc/index.html">available</a>.</p>

0 commit comments

Comments
 (0)