Minor changes in performance guide

2 files changed, 37 insertions, 26 deletions

diff --git a/railties/doc/guides/html/index.html b/railties/doc/guides/html/index.html
index b2dce5cd67..8dc8f6f95b 100644
--- a/railties/doc/guides/html/index.html
+++ b/railties/doc/guides/html/index.html
@@ -348,7 +348,7 @@ of your code.</p></div>
 </div></div>

 <div class="sidebarblock">

 <div class="sidebar-content">

-<div class="sidebar-title"><a href="performance_testing.html">Performance testing Rails Applications</a></div>

+<div class="sidebar-title"><a href="performance_testing.html">Performance Testing Rails Applications</a></div>

 <div class="admonitionblock">

 <table><tr>

 <td class="icon">

diff --git a/railties/doc/guides/html/performance_testing.html b/railties/doc/guides/html/performance_testing.html
index dbbd52fa2b..ca5070f095 100644
--- a/railties/doc/guides/html/performance_testing.html
+++ b/railties/doc/guides/html/performance_testing.html
@@ -304,8 +304,8 @@ http://www.gnu.org/software/src-highlite -->
 by Lorenzo Bettini

 http://www.lorenzobettini.it

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

-<pre><tt><span style="color: #990000">[</span>lifo@null application <span style="color: #990000">(</span>master<span style="color: #990000">)]</span>$ script/generate performance_test homepage</tt></pre></div></div>

-<div class="paragraph"><p>This will generate <tt>test/performance/homepage_test.rb</tt>:</p></div>

+<pre><tt>script/generate performance_test homepage</tt></pre></div></div>

+<div class="paragraph"><p>This generates <tt>homepage_test.rb</tt> inside <tt>test/performance</tt> directory:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -320,9 +320,8 @@ http://www.gnu.org/software/src-highlite -->
     get <span style="color: #FF0000">'/'</span>

   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>

-<div class="paragraph"><p>Which you can modify to suit your needs.</p></div>

 <h3 id="_examples">1.2. Examples</h3>

-<div class="paragraph"><p>Let&#8217;s assume your application have the following controller and model:</p></div>

+<div class="paragraph"><p>Let&#8217;s assume your application has the following controller and model:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -363,8 +362,8 @@ map<span style="color: #990000">.</span>resources <span style="color: #990000">:
   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>

 <h4 id="_controller_example">1.2.1. Controller Example</h4>

-<div class="paragraph"><p>Performance tests are special kind of integration tests. This allows you to use <tt>get</tt> and <tt>post</tt> methods inside the performance tests.</p></div>

-<div class="paragraph"><p>Performance tests for the controller code above can be something like:</p></div>

+<div class="paragraph"><p>Performance tests are a special kind of integration tests. This allows you to use <tt>get</tt> and <tt>post</tt> methods inside the performance tests.</p></div>

+<div class="paragraph"><p>Here&#8217;s the performance test for <tt>HomeController#dashboard</tt> and <tt>PostsController#create</tt>:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -389,7 +388,8 @@ http://www.gnu.org/software/src-highlite -->
 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>

 <div class="paragraph"><p>You can find more details about <tt>get</tt> and <tt>post</tt> methods in API documentation of integration testing.</p></div>

 <h4 id="_model_example">1.2.2. Model Example</h4>

-<div class="paragraph"><p>Even though performance tests are integration tests and hence closer to request/response cycle by nature, it doesn&#8217;t prevent us from testing pure model code inside. Performance test for <tt>Post</tt> model above can be somewhat like:</p></div>

+<div class="paragraph"><p>Even though the performance tests are integration tests and hence closer to request/response cycle by nature, it doesn&#8217;t prevent us from performance testing pure model code.</p></div>

+<div class="paragraph"><p>Performance test for <tt>Post</tt> model:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -409,9 +409,10 @@ http://www.gnu.org/software/src-highlite -->
   <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>

 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>

 <h3 id="_modes">1.3. Modes</h3>

-<div class="paragraph"><p>Performance test cases can be run in two modes : Benchmarking and Profling.</p></div>

+<div class="paragraph"><p>Performance tests can be run in two modes : Benchmarking and Profling.</p></div>

 <h4 id="_benchmarking">1.3.1. Benchmarking</h4>

-<div class="paragraph"><p>Benchmarking helps you find out how fast are your test cases. Each Test case is run <tt>4 times</tt> in this mode. To run performance tests in benchmarking mode:</p></div>

+<div class="paragraph"><p>Benchmarking helps find out how fast is a performance test. Each test case is run <tt>4 times</tt> in benchmarking mode.</p></div>

+<div class="paragraph"><p>To run performance tests in benchmarking mode:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -419,7 +420,8 @@ http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->

 <pre><tt>$ rake <span style="font-weight: bold"><span style="color: #0000FF">test</span></span><span style="color: #990000">:</span>benchmark</tt></pre></div></div>

 <h4 id="_profiling">1.3.2. Profiling</h4>

-<div class="paragraph"><p>Profiling helps introspect into your test cases and figure out which are the slow parts. Each Test case is run <tt>1 time</tt> in this mode. To run performance tests in profiling mode:</p></div>

+<div class="paragraph"><p>Profiling helps you introspect into a performance test and provide an in-depth picture of the slow and memory hungy parts. Each Test case is run <tt>1 time</tt> in profiling mode.</p></div>

+<div class="paragraph"><p>To run performance tests in profiling mode:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

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

 <pre><tt>$ rake <span style="font-weight: bold"><span style="color: #0000FF">test</span></span><span style="color: #990000">:</span>profile</tt></pre></div></div>

 <h3 id="_metrics">1.4. Metrics</h3>

-<div class="paragraph"><p>Benchmarking and profiling run performance test cases in various modes to help precisely figure out the where the problem lies.</p></div>

+<div class="paragraph"><p>Benchmarking and profiling run performance tests in various modes described below.</p></div>

 <h4 id="_wall_time">1.4.1. Wall Time</h4>

 <div class="paragraph"><p>Measures the real world time elapsed during the test run. It is affected by any other processes concurrently running on the system.</p></div>

 <div class="paragraph"><p>Mode : Benchmarking</p></div>

@@ -464,7 +466,7 @@ http://www.gnu.org/software/src-highlite -->
              gc_runs<span style="color: #990000">:</span> <span style="color: #993399">0</span>

              gc_time<span style="color: #990000">:</span> <span style="color: #993399">19</span> ms</tt></pre></div></div>

 <h5 id="_csv_files">CSV files</h5>

-<div class="paragraph"><p>Performance tests results are also appended to <tt>.csv</tt> files inside <tt>tmp/performance/&lt;Class&gt;#&lt;test&gt;_&lt;metric&gt;.csv</tt> file. For example, running the default <tt>BrowsingTest#test_homepage</tt> will generate following five files :</p></div>

+<div class="paragraph"><p>Performance test results are also appended to <tt>.csv</tt> files inside <tt>tmp/performance</tt>. For example, running the default <tt>BrowsingTest#test_homepage</tt> will generate following five files :</p></div>

 <div class="ulist"><ul>

 <li>

 <p>

@@ -492,8 +494,8 @@ BrowsingTest#test_homepage_wall_time.csv
 </p>

 </li>

 </ul></div>

-<div class="paragraph"><p>As the results are appended to these files each time the performance tests are run in benchmarking mode, it enables you gather data over a sustainable period of time which can be very helpful with various performance analysis.</p></div>

-<div class="paragraph"><p>Sample output of +BrowsingTest#test_homepage_wall_time.csv + :</p></div>

+<div class="paragraph"><p>As the results are appended to these files each time the performance tests are run in benchmarking mode, it enables you to collect data over a period of time which can be very helpful with various performance analysis.</p></div>

+<div class="paragraph"><p>Sample output of <tt>BrowsingTest#test_homepage_wall_time.csv</tt>:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -512,7 +514,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 the 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. Example :</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -529,7 +531,8 @@ http://www.gnu.org/software/src-highlite -->
 <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>To get the best from Rails performance test cases, you need to build a special Ruby binary with some super powers - GC patch for measuring GC Runs/Time and memory/object allocation profiling. This process is very straight forward. If you&#8217;ve never compiled a Ruby binary before, you can follow the following steps to build a ruby binary inside your home directory:</p></div>

+<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>

 <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>

@@ -559,7 +562,7 @@ 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>

-<div class="paragraph"><p>For convenience, add the following lines in your ~/.profile after replacing &lt;username&gt; with your :</p></div>

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

 <div class="listingblock">

 <div class="content">

 <pre><tt>alias gcruby='~/rubygc/bin/ruby'

@@ -568,7 +571,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_some_basic_gems">1.6.6. Install rubygems and some basic gems</h4>

+<h4 id="_install_rubygems_and_dependency_gems">1.6.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>

@@ -604,11 +607,11 @@ alias gcrails='~/rubygc/bin/rails'</tt></pre>
 <pre><tt>[lifo@null mysql]$ gcruby extconf.rb --with-mysql-config

 [lifo@null mysql]$ make &amp;&amp; make install</tt></pre>

 </div></div>

-<div class="paragraph"><p>And you&#8217;re ready to go. Don&#8217;t forget to use <tt>gcruby</tt> and <tt>gcrake</tt> aliases when running performance tests!</p></div>

+<div class="paragraph"><p>And you&#8217;re ready to go. Don&#8217;t forget to use <tt>gcruby</tt> and <tt>gcrake</tt> aliases when running the performance tests.</p></div>

 </div>

 <h2 id="_helper_methods">2. Helper methods</h2>

 <div class="sectionbody">

-<div class="paragraph"><p>Rails provides various helper methods inside Active Record, Action Controller and Action View to measure the time taken by a specific code. The method is called <tt>benchmark()</tt> in all three components.</p></div>

+<div class="paragraph"><p>Rails provides various helper methods inside Active Record, Action Controller and Action View to measure the time taken by a given piece of code. The method is called <tt>benchmark()</tt> in all the three components.</p></div>

 <h3 id="_model">2.1. Model</h3>

 <div class="listingblock">

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

@@ -620,7 +623,7 @@ http://www.gnu.org/software/src-highlite -->
   project<span style="color: #990000">.</span>create_manager<span style="color: #990000">(</span><span style="color: #FF0000">"name"</span> <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"David"</span><span style="color: #990000">)</span>

   project<span style="color: #990000">.</span>milestones <span style="color: #990000">&lt;&lt;</span> Milestone<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">)</span>

 <span style="font-weight: bold"><span style="color: #0000FF">end</span></span></tt></pre></div></div>

-<div class="paragraph"><p>The above code benchmarks the multiple statments enclosed inside <tt>Project.benchmark("Creating project") do..end</tt> block and prints the results to the log file. The statement inside log files will look like:</p></div>

+<div class="paragraph"><p>This benchmarks the code enclosed in <tt>Project.benchmark("Creating project") do..end</tt> block and prints the result to the log file:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -629,7 +632,15 @@ http://www.gnu.org/software/src-highlite -->
 <pre><tt>Creating projectem <span style="color: #990000">(</span><span style="color: #993399">185</span><span style="color: #990000">.</span>3ms<span style="color: #990000">)</span></tt></pre></div></div>

 <div class="paragraph"><p>Please refer to <a href="http://api.rubyonrails.com/classes/ActiveRecord/Base.html#M001336">API docs</a> for optional options to <tt>benchmark()</tt></p></div>

 <h3 id="_controller">2.2. Controller</h3>

-<div class="paragraph"><p>Similarly, you could use this helper method inside <a href="http://api.rubyonrails.com/classes/ActionController/Benchmarking/ClassMethods.html#M000715">controllers</a> ( Note that it&#8217;s a class method here ):</p></div>

+<div class="paragraph"><p>Similarly, you could use this helper method inside <a href="http://api.rubyonrails.com/classes/ActionController/Benchmarking/ClassMethods.html#M000715">controllers</a></p></div>

+<div class="admonitionblock">

+<table><tr>

+<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>

+</tr></table>

+</div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -654,7 +665,7 @@ http://www.gnu.org/software/src-highlite -->
 </div>

 <h2 id="_request_logging">3. Request Logging</h2>

 <div class="sectionbody">

-<div class="paragraph"><p>Rails log files containt basic but very useful information about the time taken to serve each request. A typical log entry looks something like :</p></div>

+<div class="paragraph"><p>Rails log files containt very useful information about the time taken to serve each request. Here&#8217;s a typical log file entry:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -664,7 +675,7 @@ http://www.gnu.org/software/src-highlite -->
 Rendering template within layouts<span style="color: #990000">/</span>items

 Rendering items<span style="color: #990000">/</span>index

 Completed <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> 5ms <span style="color: #990000">(</span>View<span style="color: #990000">:</span> <span style="color: #993399">2</span><span style="color: #990000">,</span> DB<span style="color: #990000">:</span> <span style="color: #993399">0</span><span style="color: #990000">)</span> <span style="color: #990000">|</span> <span style="color: #993399">200</span> OK <span style="color: #990000">[</span>http<span style="color: #990000">:</span><span style="color: #FF6600">//0.0.0.0/</span>items<span style="color: #990000">]</span></tt></pre></div></div>

-<div class="paragraph"><p>For this section, we&#8217;re only interested in the last line from that log entry:</p></div>

+<div class="paragraph"><p>For this section, we&#8217;re only interested in the last line:</p></div>

 <div class="listingblock">

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

 by Lorenzo Bettini

@@ -721,7 +732,7 @@ http://www.gnu.org/software/src-highlite -->
 <div class="ulist"><ul>

 <li>

 <p>

-January 9, 2009: Rewrite by Pratik

+January 9, 2009: Complete rewrite by Pratik

 </p>

 </li>

 <li>