Add a note about tuning perf test runs

1 files changed, 55 insertions, 17 deletions

diff --git a/railties/doc/guides/html/performance_testing.html b/railties/doc/guides/html/performance_testing.html
index ca5070f095..52c2a3599d 100644
--- a/railties/doc/guides/html/performance_testing.html
+++ b/railties/doc/guides/html/performance_testing.html
@@ -212,6 +212,8 @@ ul#navMain {
 						
 							<li><a href="#_understanding_the_output">Understanding the output</a></li>
 						
+							<li><a href="#_tuning_test_runs">Tuning Test Runs</a></li>
+						
 							<li><a href="#gc">Installing GC Patched Ruby</a></li>
 						
 						</ul>
@@ -232,10 +234,17 @@ ul#navMain {
 					<a href="#_request_logging">Request Logging</a>
 					</li>
 					<li>
-					<a href="#_other_profiling_tools">Other Profiling Tools</a>
+					<a href="#_useful_profiling_tools">Useful Profiling Tools</a>
+						<ul>
+						
+							<li><a href="#_rails_plugins_and_gems">Rails Plugins and Gems</a></li>
+						
+							<li><a href="#_external">External</a></li>
+						
+						</ul>
 					</li>
 					<li>
-					<a href="#_commercial_products">Commercial products</a>
+					<a href="#_commercial_products">Commercial Products</a>
 					</li>
 					<li>
 					<a href="#_changelog">Changelog</a>
@@ -514,7 +523,7 @@ http://www.gnu.org/software/src-highlite -->
 <span style="color: #993399">0.00771250000000012</span><span style="color: #990000">,</span><span style="color: #993399">2009</span>-<span style="color: #993399">01</span>-09T15<span style="color: #990000">:</span><span style="color: #993399">46</span><span style="color: #990000">:</span>03Z<span style="color: #990000">,,</span><span style="color: #993399">2.3</span><span style="color: #990000">.</span><span style="color: #993399">0</span><span style="color: #990000">.</span>master<span style="color: #990000">.</span><span style="color: #993399">859e150</span><span style="color: #990000">,</span>ruby-<span style="color: #993399">1.8</span><span style="color: #990000">.</span><span style="color: #993399">6.110</span><span style="color: #990000">,</span>i686-darwin<span style="color: #993399">9.0</span><span style="color: #990000">.</span><span style="color: #993399">0</span></tt></pre></div></div>

 <h4 id="_profiling_2">1.5.2. Profiling</h4>

 <h5 id="_command_line_2">Command line</h5>

-<div class="paragraph"><p>This is a very basic form of output in profiling mode. Example :</p></div>

+<div class="paragraph"><p>This is a very basic form of output in profiling mode:</p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

@@ -529,13 +538,23 @@ http://www.gnu.org/software/src-highlite -->
 <h5 id="_graph">Graph</h5>

 <div class="paragraph"><p>Graph output shows how long each method takes to run, which methods call it and which methods it calls. <a href="http://ruby-prof.rubyforge.org/files/examples/graph_txt.html">Check ruby prof documentation for a better explaination</a>.</p></div>

 <h5 id="_tree">Tree</h5>

-<div class="paragraph"><p>Tree output is profiling information in calltree format for use by kcachegrind and similar tools.</p></div>

-<h3 id="gc">1.6. Installing GC Patched Ruby</h3>

+<div class="paragraph"><p>Tree output is profiling information in calltree format for use by <a href="http://kcachegrind.sourceforge.net/html/Home.html">kcachegrind</a> and similar tools.</p></div>

+<h3 id="_tuning_test_runs">1.6. Tuning Test Runs</h3>

+<div class="paragraph"><p>By default, each performance test is run <tt>4 times</tt> in benchmarking model and <tt>1 time</tt> in profiling. However, test runs can easily be configured.</p></div>

+<div class="admonitionblock">

+<table><tr>

+<td class="icon">

+<img src="./images/icons/caution.png" alt="Caution" />

+</td>

+<td class="content">That&#8217;s a lie. But not for long.</td>

+</tr></table>

+</div>

+<h3 id="gc">1.7. Installing GC Patched Ruby</h3>

 <div class="paragraph"><p>To get the best from Rails performance tests, you need to build a special Ruby binary with some super powers - <a href="http://rubyforge.org/tracker/download.php/1814/7062/17676/3291/ruby186gc.patch">GC patch</a> for measuring GC Runs/Time and memory/object allocation.</p></div>

 <div class="paragraph"><p>The process is fairly straight forward. If you&#8217;ve never compiled a Ruby binary before, follow the following steps to build a ruby binary inside your home directory:</p></div>

-<h4 id="_instllation">1.6.1. Instllation</h4>

+<h4 id="_instllation">1.7.1. Instllation</h4>

 <div class="paragraph"><p>Compile Ruby and apply this <a href="http://rubyforge.org/tracker/download.php/1814/7062/17676/3291/ruby186gc.patch">GC Patch</a>:</p></div>

-<h4 id="_download_and_extract">1.6.2. Download and Extract</h4>

+<h4 id="_download_and_extract">1.7.2. Download and Extract</h4>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

@@ -545,14 +564,14 @@ http://www.gnu.org/software/src-highlite -->
 <span style="color: #990000">[</span>lifo@null <span style="color: #990000">~]</span>$ wget <span style="color: #990000">&lt;</span>download the latest stable ruby from ftp<span style="color: #990000">:</span>//ftp<span style="color: #990000">.</span>ruby-lang<span style="color: #990000">.</span>org/pub/ruby<span style="color: #990000">&gt;</span>

 <span style="color: #990000">[</span>lifo@null <span style="color: #990000">~]</span>$ tar -xzvf <span style="color: #990000">&lt;</span>ruby-version<span style="color: #990000">.</span>tar<span style="color: #990000">.</span>gz<span style="color: #990000">&gt;</span>

 <span style="color: #990000">[</span>lifo@null <span style="color: #990000">~]</span>$ cd <span style="color: #990000">&lt;</span>ruby-version<span style="color: #990000">&gt;</span></tt></pre></div></div>

-<h4 id="_apply_the_patch">1.6.3. Apply the patch</h4>

+<h4 id="_apply_the_patch">1.7.3. Apply the patch</h4>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

 by Lorenzo Bettini

 http://www.lorenzobettini.it

 http://www.gnu.org/software/src-highlite -->

 <pre><tt><span style="color: #990000">[</span>lifo@null ruby-version<span style="color: #990000">]</span>$ curl http<span style="color: #990000">:</span>//rubyforge<span style="color: #990000">.</span>org/tracker/download<span style="color: #990000">.</span>php<span style="color: #990000">/</span><span style="color: #993399">1814</span><span style="color: #990000">/</span><span style="color: #993399">7062</span><span style="color: #990000">/</span><span style="color: #993399">17676</span><span style="color: #990000">/</span><span style="color: #993399">3291</span>/ruby186gc<span style="color: #990000">.</span>patch <span style="color: #990000">|</span> patch -p<span style="color: #993399">0</span></tt></pre></div></div>

-<h4 id="_configure_and_install">1.6.4. Configure and Install</h4>

+<h4 id="_configure_and_install">1.7.4. Configure and Install</h4>

 <div class="paragraph"><p>The following will install ruby in your home directory&#8217;s <tt>/rubygc</tt> directory. Make sure to replace <tt>&lt;homedir&gt;</tt> with a full patch to your actual home directory.</p></div>

 <div class="listingblock">

 <div class="content"><!-- Generator: GNU source-highlight 2.9

@@ -561,7 +580,7 @@ http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->

 <pre><tt><span style="color: #990000">[</span>lifo@null ruby-version<span style="color: #990000">]</span>$ <span style="color: #990000">.</span>/configure --prefix<span style="color: #990000">=/&lt;</span>homedir<span style="color: #990000">&gt;</span>/rubygc

 <span style="color: #990000">[</span>lifo@null ruby-version<span style="color: #990000">]</span>$ make <span style="color: #990000">&amp;&amp;</span> make install</tt></pre></div></div>

-<h4 id="_prepare_aliases">1.6.5. Prepare aliases</h4>

+<h4 id="_prepare_aliases">1.7.5. Prepare aliases</h4>

 <div class="paragraph"><p>For convenience, add the following lines in your <tt>~/.profile</tt>:</p></div>

 <div class="listingblock">

 <div class="content">

@@ -571,7 +590,7 @@ alias gcgem='~/rubygc/bin/gem'
 alias gcirb='~/rubygc/bin/irb'

 alias gcrails='~/rubygc/bin/rails'</tt></pre>

 </div></div>

-<h4 id="_install_rubygems_and_dependency_gems">1.6.6. Install rubygems and dependency gems</h4>

+<h4 id="_install_rubygems_and_dependency_gems">1.7.6. Install rubygems and dependency gems</h4>

 <div class="paragraph"><p>Download <a href="http://rubyforge.org/projects/rubygems">Rubygems</a> and install it from source. Rubygem&#8217;s README file should have necessary installation instructions.</p></div>

 <div class="paragraph"><p>Additionally, installa the following gems :</p></div>

 <div class="ulist"><ul>

@@ -638,7 +657,7 @@ http://www.gnu.org/software/src-highlite -->
 <td class="icon">

 <img src="./images/icons/note.png" alt="Note" />

 </td>

-<td class="content"><tt>benchmark</tt> it&#8217;s a class method inside controllers.</td>

+<td class="content"><tt>benchmark</tt> is a class method inside controllers</td>

 </tr></table>

 </div>

 <div class="listingblock">

@@ -685,27 +704,46 @@ http://www.gnu.org/software/src-highlite -->
 <div class="paragraph"><p>This data is fairly straight forward to understand. Rails uses millisecond(ms) as the metric to measures the time taken. The complete request spent 5 ms inside Rails, out of which 2 ms were spent rendering views and none was spent communication with the database. It&#8217;s safe to assume that the remaining 3 ms were spent inside the controller.</p></div>

 <div class="paragraph"><p>Michael Koziarski has an <a href="http://www.therailsway.com/2009/1/6/requests-per-second">interesting blog post</a> explaining the importance of using milliseconds as the metric.</p></div>

 </div>

-<h2 id="_other_profiling_tools">4. Other Profiling Tools</h2>

+<h2 id="_useful_profiling_tools">4. Useful Profiling Tools</h2>

 <div class="sectionbody">

+<h3 id="_rails_plugins_and_gems">4.1. Rails Plugins and Gems</h3>

 <div class="ulist"><ul>

 <li>

 <p>

-<a href="http://www.hpl.hp.com/research/linux/httperf/">httperf</a>

+<a href="http://rails-analyzer.rubyforge.org/">Rails Analyzer</a>

 </p>

 </li>

 <li>

 <p>

-<a href="http://rails-analyzer.rubyforge.org/">Rails Analyzer</a>

+<a href="http://www.flyingmachinestudios.com/projects/">Palmist</a>

 </p>

 </li>

 <li>

 <p>

-<a href="http://www.flyingmachinestudios.com/projects/">Palmist</a>

+<a href="http://github.com/josevalim/rails-footnotes/tree/master">Rails Footnotes</a>

+</p>

+</li>

+</ul></div>

+<h3 id="_external">4.2. External</h3>

+<div class="ulist"><ul>

+<li>

+<p>

+<a href="http://www.hpl.hp.com/research/linux/httperf">httperf</a>

+</p>

+</li>

+<li>

+<p>

+<a href="http://httpd.apache.org/docs/2.2/programs/ab.html">ab</a>

+</p>

+</li>

+<li>

+<p>

+<a href="http://jakarta.apache.org/jmeter">JMeter</a>

 </p>

 </li>

 </ul></div>

 </div>

-<h2 id="_commercial_products">5. Commercial products</h2>

+<h2 id="_commercial_products">5. Commercial Products</h2>

 <div class="sectionbody">

 <div class="paragraph"><p>Rails has been lucky to have three startups dedicated to Rails specific performance tools:</p></div>

 <div class="ulist"><ul>