You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>This section describes advanced usage of ruby-prof. Additional documentation for every class is also <ahref="../#api-documentation">available</a>.</p>
830
+
<p>This section describes advanced usage of ruby-prof. Additional documentation for every class is also <ahref="../#api-documentation">available</a>. For workflow guidance, see <ahref="../best-practices/">Best Practices</a>.</p>
<p>ruby-prof understands the following options when profiling code:</p>
806
833
<p><strong>measure_mode</strong> - What ruby-prof should measure. For more information see the <ahref="#measurement-mode">Measurement Mode</a> section.</p>
<p>Note the <code>RubyProf::ALLOCATIONS</code> measure mode is slightly different than tracking allocations. The measurement mode provides high level information about the number of allocations performed in each method. In contrast, tracking allocations provides detailed information about the type, number, memory usage and location of each allocation. Currently, to see allocations results you must use the <code>RubyProf::GraphHtmlPrinter</code>.</p>
865
+
<p>Note the <code>RubyProf::ALLOCATIONS</code> measure mode is slightly different than tracking allocations. The measurement mode provides high level information about the number of allocations performed in each method. In contrast, tracking allocations provides detailed information about allocation type, count, and source location. Currently, to see allocations results you must use the <code>RubyProf::GraphHtmlPrinter</code>.</p>
<p>ruby-prof can profile multiple threads. Sometimes this can be overwhelming. For example, assume you want to determine why your tests are running slowly. If you are using minitest, it will run your tests in parallel by spawning tens of worker threads (note to tell minitest to use a single thread set the N environmental variable like this ENV = 0). Thus, ruby-prof provides two options to specify which threads should be profiled:</p>
867
+
<p>ruby-prof can profile multiple threads. Sometimes this can be overwhelming. For example, assume you want to determine why your tests are running slowly. If you are using minitest, it can run tests in parallel by spawning worker threads (to force a single worker, set <code>N=0</code> when running tests). Thus, ruby-prof provides two options to specify which threads should be profiled:</p>
841
868
<p><strong>exclude_threads</strong> - Array of threads which should not be profiled.</p>
842
869
<p><strong>include_threads</strong> - Array of threads which should be profiled. All other threads will be ignored.</p>
<p>It can be helpful to save the results of a profiling run for later analysis. Results can be saved using Ruby's <ahref="https://docs.ruby-lang.org/en/master/Marshal.html">marshal</a> library.</p>
<p>Once a profile is completed, you can either generate a <ahref="../reports/">report</a> via a printer or <ahref="../advanced-usage/#saving-results">save</a> the results for later analysis. For a list of profiling options, please see the <ahref="../advanced-usage/#profiling-options">Profiling Options</a> section.</p>
752
+
<p>Once a profile is completed, you can either generate a <ahref="../reports/">report</a> via a printer or <ahref="../advanced-usage/#saving-results">save</a> the results for later analysis. For a list of profiling options, please see the <ahref="../advanced-usage/#profiling-options">Profiling Options</a> section.
753
+
If you are unsure which report to generate first, see <ahref="../reports/#choosing-a-report">Choosing a Report</a>.</p>
726
754
<p>However, using ruby-prof also comes with two caveats:</p>
727
755
<ul>
728
756
<li>To use ruby-prof you generally need to include a few lines of extra code in your program (although see <ahref="../getting-started/#command-line">command line usage</a>)</li>
729
-
<li>Using ruby-prof will cause your program to run slower (see <ahref="#performance">Performance</a> section)</li>
757
+
<li>Using ruby-prof will cause your program to run slower (see <ahref="../#performance">Performance</a> section)</li>
730
758
</ul>
731
759
<p>Most of the time, these two caveats are acceptable. But if you need to determine why a program running in production is slow or hung, a sampling profiler will be a better choice. Excellent choices include <ahref="https://github.com/tmm1/stackprof">stackprof</a> or <ahref="https://rbspy.github.io/">rbspy</a>.</p>
732
760
<p>If you are just interested in memory usage, you may also want to checkout the <ahref="https://github.com/SamSaffron/memory_profiler">memory_profiler</a> gem (although ruby-prof provides similar information).</p>
<p>ruby-prof is a <ahref="./comparison/#tracing-vs-sampling">tracing</a> profiler for MRI Ruby with a long <ahref="./history/">history</a> that dates back to 2005! Its features include:</p>
750
+
<p>ruby-prof is a <ahref="./alternatives/#tracing-vs-sampling">tracing</a> profiler for MRI Ruby with a long <ahref="./history/">history</a> that dates back to 2005! Its features include:</p>
724
751
<ul>
725
752
<li>Measurement Modes - ruby-prof can measure program <ahref="advanced-usage/#wall-time">wall time</a>, <ahref="advanced-usage/#process-time">process time</a> and <ahref="advanced-usage/#object-allocations">object allocations</a>.</li>
726
753
<li>Reports - ruby-prof can generate <ahref="reports/#flat">flat</a>, <ahref="reports/#graph-text">graph (text)</a>, <ahref="reports/#graph-html">graph (HTML)</a>, <ahref="reports/#flame-graph">flame graph</a>, <ahref="reports/#call-stack">call stack</a>, <ahref="reports/#graphviz">graphviz</a>, <ahref="reports/#cachegrind">cachegrind</a>, and <ahref="reports/#call-info-report">call info</a> reports.</li>
0 commit comments