Added RJS, memory leaks and plugins chapters to Debugging Rails Applications guide. Generated Guides.

3 files changed, 255 insertions, 3 deletions

diff --git a/railties/doc/guides/html/debugging_rails_applications.html b/railties/doc/guides/html/debugging_rails_applications.html
index bf1e442d59..0fdc1b0a1f 100644
--- a/railties/doc/guides/html/debugging_rails_applications.html
+++ b/railties/doc/guides/html/debugging_rails_applications.html
@@ -208,6 +208,8 @@ ul#navMain {
 						
 							<li><a href="#_inspect">inspect</a></li>
 						
+							<li><a href="#_debugging_javascript">Debugging Javascript</a></li>
+						
 						</ul>
 					</li>
 					<li>
@@ -253,6 +255,19 @@ ul#navMain {
 						</ul>
 					</li>
 					<li>
+					<a href="#_debugging_memory_leaks">Debugging Memory Leaks</a>
+						<ul>
+						
+							<li><a href="#_bleak_house">Bleak House</a></li>
+						
+							<li><a href="#_valgrind">Valgrind</a></li>
+						
+						</ul>
+					</li>
+					<li>
+					<a href="#_plugins_for_debugging">Plugins for Debugging</a>
+					</li>
+					<li>
 					<a href="#_references">References</a>
 					</li>
 					<li>
@@ -397,6 +412,32 @@ http://www.gnu.org/software/src-highlite -->
 

 Title: Rails debugging guide

 </tt></pre></div></div>

+<h3 id="_debugging_javascript">1.4. Debugging Javascript</h3>

+<div class="para"><p>Rails has built-in support to debug RJS, to active it, set <tt>ActionView::Base.debug_rjs</tt> to <em>true</em>, this will specify whether RJS responses should be wrapped in a try/catch block that alert()s the caught exception (and then re-raises it).</p></div>

+<div class="para"><p>To enable it, add the following in the <tt>Rails::Initializer do |config|</tt> block inside <tt>environment.rb</tt>:</p></div>

+<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>config<span style="color: #990000">.</span>action_view<span style="color: #990000">[:</span>debug_rjs<span style="color: #990000">]</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>

+</tt></pre></div></div>

+<div class="para"><p>Or, at any time, setting <tt>ActionView::Base.debug_rjs</tt> to <em>true</em>:</p></div>

+<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>ActionView<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>debug_rjs <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>

+</tt></pre></div></div>

+<div class="admonitionblock">

+<table><tr>

+<td class="icon">

+<img src="./images/icons/tip.png" alt="Tip" />

+</td>

+<td class="content">For more information on debugging javascript refer to <a href="http://getfirebug.com/">Firebug</a>, the popular debugger for Firefox.</td>

+</tr></table>

+</div>

 </div>

 <h2 id="_the_logger">2. The Logger</h2>

 <div class="sectionbody">

@@ -978,7 +1019,104 @@ set forcestep
 set listsize 25

 </tt></pre></div></div>

 </div>

-<h2 id="_references">4. References</h2>

+<h2 id="_debugging_memory_leaks">4. Debugging Memory Leaks</h2>

+<div class="sectionbody">

+<div class="para"><p>A Ruby application (on Rails or not), can leak memory whether in the Ruby code but also in the C code.</p></div>

+<div class="para"><p>In this section, you will learn how to find and fix this leaks by using Bleak House and Valgrind debugging tools.</p></div>

+<h3 id="_bleak_house">4.1. Bleak House</h3>

+<div class="para"><p><a href="http://github.com/fauna/bleak_house/tree/master">Bleak House</a> is a library for finding memory leaks.</p></div>

+<div class="para"><p>If a Ruby object does not go out of scope, the Ruby Garbage Collector won't sweep it since it is referenced somewhere, this leaks can grow slowly and your application will consume more and more memory gradually affecting the overall system performance. This tool will help you find leaks on the Ruby heap.</p></div>

+<div class="para"><p>To install it run:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><tt>sudo gem install bleak_house</tt></pre>

+</div></div>

+<div class="para"><p>Then setup you application for profiling, add the following at the bottom of config/environment.rb:</p></div>

+<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="font-weight: bold"><span style="color: #000080">require</span></span> <span style="color: #FF0000">'bleak_house'</span> <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> ENV<span style="color: #990000">[</span><span style="color: #FF0000">'BLEAK_HOUSE'</span><span style="color: #990000">]</span>

+</tt></pre></div></div>

+<div class="para"><p>Start a server instance with Bleak House integration:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><tt>RAILS_ENV=production BLEAK_HOUSE=1 ruby-bleak-house ./script/server</tt></pre>

+</div></div>

+<div class="para"><p>Make sure to run a couple hundred requests to get better data samples, hit <tt>CTRL-C</tt>. The server will stop and Bleak House will produce a dumpfile in <tt>/tmp</tt>:</p></div>

+<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>** BleakHouse: working...

+** BleakHouse: complete

+** Bleakhouse: run 'bleak /tmp/bleak.5979.0.dump' to analyze.

+</tt></pre></div></div>

+<div class="para"><p>To analyze it, just run the listed command. The top 20 leakiest lines will be listed:</p></div>

+<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>  191691 total objects

+  Final heap size 191691 filled, 220961 free

+  Displaying top 20 most common line/class pairs

+  89513 __null__:__null__:__node__

+  41438 __null__:__null__:String

+  2348 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:Array

+  1508 /opt/local//lib/ruby/gems/1.8/specifications/gettext-1.90.0.gemspec:14:String

+  1021 /opt/local//lib/ruby/gems/1.8/specifications/heel-0.2.0.gemspec:14:String

+   951 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:111:String

+   935 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:String

+   834 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:146:Array

+  ...

+</tt></pre></div></div>

+<div class="para"><p>This way you can find where you application is leaking memory and fix it.</p></div>

+<div class="para"><p>If <a href="http://github.com/fauna/bleak_house/tree/master">BleakHouse</a> doesn't report any heap growth but you still have memory growth, you might have a broken C extension, or real leak in the interpreter, try using Valgrind.</p></div>

+<h3 id="_valgrind">4.2. Valgrind</h3>

+<div class="para"><p><a href="http://valgrind.org/">Valgrind</a> is a Linux (only works on Linux) application for detecting C-based memory leaks and race conditions.</p></div>

+<div class="para"><p>There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. For example, a C extension in the interpreter calls <tt>malloc()</tt> but is doesn't properly call <tt>free()</tt>, this memory won't be available until the app terminates.</p></div>

+<div class="para"><p>For further information on how to install and using with Ruby, refer to the <a href="http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/">Valgrind and Ruby Evan Weaver's article</a>.</p></div>

+</div>

+<h2 id="_plugins_for_debugging">5. Plugins for Debugging</h2>

+<div class="sectionbody">

+<div class="para"><p>To make life easier Rails offer plugins, some of them will help you to find errors and debug your application. Here is a list of useful plugins for debugging:</p></div>

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

+<li>

+<p>

+<a href="http://github.com/drnic/rails-footnotes/tree/master">Footnotes</a>: Every Rails page has footnotes that link give request information and link back to your source via TextMate.

+</p>

+</li>

+<li>

+<p>

+<a href="http://github.com/ntalbott/query_trace/tree/master">Query Trace</a>: Adds query origin tracing to your logs.

+</p>

+</li>

+<li>

+<p>

+<a href="http://github.com/dan-manges/query_stats/tree/master">Query Stats</a>: A Rails plugin to track database queries.

+</p>

+</li>

+<li>

+<p>

+<a href="http://code.google.com/p/query-reviewer/">Query Reviewer</a>: This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of query warnings that it analyzed.

+</p>

+</li>

+<li>

+<p>

+<a href="http://github.com/rails/exception_notification/tree/master">Exception Notifier</a>: Provides a mailer object and a default set of templates for sending email notifications when errors occur in a Rails application.

+</p>

+</li>

+<li>

+<p>

+<a href="http://github.com/defunkt/exception_logger/tree/master">Exception Logger</a>: Logs your Rails exceptions in the database and provides a funky web interface to manage them.

+</p>

+</li>

+</ul></div>

+</div>

+<h2 id="_references">6. References</h2>

 <div class="sectionbody">

 <div class="ilist"><ul>

 <li>

@@ -1026,14 +1164,24 @@ set listsize 25
 <a href="http://wiki.rubyonrails.org/rails/pages/HowtoConfigureLogging">Ruby on Rails Wiki: How to Configure Logging</a>

 </p>

 </li>

+<li>

+<p>

+<a href="http://blog.evanweaver.com/files/doc/fauna/bleak_house/files/README.html">Bleak House Documentation</a>

+</p>

+</li>

 </ul></div>

 </div>

-<h2 id="_changelog">5. Changelog</h2>

+<h2 id="_changelog">7. Changelog</h2>

 <div class="sectionbody">

 <div class="para"><p><a href="http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/5">Lighthouse ticket</a></p></div>

 <div class="ilist"><ul>

 <li>

 <p>

+November 3, 2008: Added RJS, memory leaks and plugins chapters by <a href="../authors.html#miloops">Emilio Tagua</a>

+</p>

+</li>

+<li>

+<p>

 October 19, 2008: Copy editing pass by <a href="../authors.html#mgunderloy">Mike Gunderloy</a>

 </p>

 </li>

diff --git a/railties/doc/guides/html/migrations.html b/railties/doc/guides/html/migrations.html
index fd466d3a02..5d0f450634 100644
--- a/railties/doc/guides/html/migrations.html
+++ b/railties/doc/guides/html/migrations.html
@@ -717,7 +717,7 @@ version is the numerical prefix on the migration's filename. For example to migr
 <div class="content">

 <pre><tt>rake db:rollback STEP=3</tt></pre>

 </div></div>

-<div class="para"><p>will run the <tt>down</tt> method fron the last 3 migrations.</p></div>

+<div class="para"><p>will run the <tt>down</tt> method from the last 3 migrations.</p></div>

 <div class="para"><p>The <tt>db:migrate:redo</tt> task is a shortcut for doing a rollback and then migrating back up again. As with the <tt>db:rollback</tt> task you can use the <tt>STEP</tt> parameter if you need to go more than one version back, for example</p></div>

 <div class="listingblock">

 <div class="content">

diff --git a/railties/doc/guides/source/debugging_rails_applications.txt b/railties/doc/guides/source/debugging_rails_applications.txt
index 24eb0c0431..7271a05666 100644
--- a/railties/doc/guides/source/debugging_rails_applications.txt
+++ b/railties/doc/guides/source/debugging_rails_applications.txt
@@ -101,6 +101,27 @@ Will be rendered as follows:
 Title: Rails debugging guide
 ----------------------------------------------------------------------------
 
+=== Debugging Javascript
+
+Rails has built-in support to debug RJS, to active it, set `ActionView::Base.debug_rjs` to _true_, this will specify whether RJS responses should be wrapped in a try/catch block that alert()s the caught exception (and then re-raises it).
+
+To enable it, add the following in the `Rails::Initializer do |config|` block inside +environment.rb+:
+
+[source, ruby]
+----------------------------------------------------------------------------
+config.action_view[:debug_rjs] = true
+----------------------------------------------------------------------------
+
+Or, at any time, setting `ActionView::Base.debug_rjs` to _true_:
+
+[source, ruby]
+----------------------------------------------------------------------------
+ActionView::Base.debug_rjs = true
+----------------------------------------------------------------------------
+
+[TIP]
+For more information on debugging javascript refer to link:http://getfirebug.com/[Firebug], the popular debugger for Firefox.
+
 == The Logger
 
 It can also be useful to save information to log files at runtime. Rails maintains a separate log file for each runtime environment.
@@ -617,6 +638,87 @@ set forcestep
 set listsize 25
 ----------------------------------------------------------------------------
 
+== Debugging Memory Leaks
+
+A Ruby application (on Rails or not), can leak memory whether in the Ruby code but also in the C code.
+
+In this section, you will learn how to find and fix this leaks by using Bleak House and Valgrind debugging tools.
+
+=== Bleak House
+
+link:http://github.com/fauna/bleak_house/tree/master[Bleak House] is a library for finding memory leaks.
+
+If a Ruby object does not go out of scope, the Ruby Garbage Collector won't sweep it since it is referenced somewhere, this leaks can grow slowly and your application will consume more and more memory gradually affecting the overall system performance. This tool will help you find leaks on the Ruby heap.
+
+To install it run:
+
+----------------------------------------------------------------------------
+sudo gem install bleak_house
+----------------------------------------------------------------------------
+
+Then setup you application for profiling, add the following at the bottom of config/environment.rb:
+
+[source, ruby]
+----------------------------------------------------------------------------
+require 'bleak_house' if ENV['BLEAK_HOUSE']
+----------------------------------------------------------------------------
+
+Start a server instance with Bleak House integration:
+
+----------------------------------------------------------------------------
+RAILS_ENV=production BLEAK_HOUSE=1 ruby-bleak-house ./script/server
+----------------------------------------------------------------------------
+
+Make sure to run a couple hundred requests to get better data samples, hit `CTRL-C`. The server will stop and Bleak House will produce a dumpfile in `/tmp`:
+
+[source, log]
+----------------------------------------------------------------------------
+** BleakHouse: working...
+** BleakHouse: complete
+** Bleakhouse: run 'bleak /tmp/bleak.5979.0.dump' to analyze.
+----------------------------------------------------------------------------
+ 
+To analyze it, just run the listed command. The top 20 leakiest lines will be listed: 
+
+[source, log]
+----------------------------------------------------------------------------
+  191691 total objects
+  Final heap size 191691 filled, 220961 free
+  Displaying top 20 most common line/class pairs
+  89513 __null__:__null__:__node__
+  41438 __null__:__null__:String
+  2348 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:Array
+  1508 /opt/local//lib/ruby/gems/1.8/specifications/gettext-1.90.0.gemspec:14:String
+  1021 /opt/local//lib/ruby/gems/1.8/specifications/heel-0.2.0.gemspec:14:String
+   951 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:111:String
+   935 /opt/local//lib/ruby/site_ruby/1.8/rubygems/specification.rb:557:String
+   834 /opt/local//lib/ruby/site_ruby/1.8/rubygems/version.rb:146:Array
+  ...
+----------------------------------------------------------------------------
+
+This way you can find where you application is leaking memory and fix it.
+
+If link:http://github.com/fauna/bleak_house/tree/master[BleakHouse] doesn't report any heap growth but you still have memory growth, you might have a broken C extension, or real leak in the interpreter, try using Valgrind.
+
+=== Valgrind
+
+link:http://valgrind.org/[Valgrind] is a Linux (only works on Linux) application for detecting C-based memory leaks and race conditions.
+
+There are Valgrind tools that can automatically detect many memory management and threading bugs, and profile your programs in detail. For example, a C extension in the interpreter calls `malloc()` but is doesn't properly call `free()`, this memory won't be available until the app terminates.
+
+For further information on how to install and using with Ruby, refer to the link:http://blog.evanweaver.com/articles/2008/02/05/valgrind-and-ruby/[Valgrind and Ruby Evan Weaver's article].
+
+== Plugins for Debugging
+
+To make life easier Rails offer plugins, some of them will help you to find errors and debug your application. Here is a list of useful plugins for debugging:
+
+* link:http://github.com/drnic/rails-footnotes/tree/master[Footnotes]: Every Rails page has footnotes that link give request information and link back to your source via TextMate.
+* link:http://github.com/ntalbott/query_trace/tree/master[Query Trace]: Adds query origin tracing to your logs.
+* link:http://github.com/dan-manges/query_stats/tree/master[Query Stats]: A Rails plugin to track database queries. 
+* link:http://code.google.com/p/query-reviewer/[Query Reviewer]: This rails plugin not only runs "EXPLAIN" before each of your select queries in development, but provides a small DIV in the rendered output of each page with the summary of query warnings that it analyzed.
+* link:http://github.com/rails/exception_notification/tree/master[Exception Notifier]: Provides a mailer object and a default set of templates for sending email notifications when errors occur in a Rails application.
+* link:http://github.com/defunkt/exception_logger/tree/master[Exception Logger]: Logs your Rails exceptions in the database and provides a funky web interface to manage them.
+
 == References
 
 * link:http://www.datanoise.com/ruby-debug[ruby-debug Homepage]
@@ -628,10 +730,12 @@ set listsize 25
 * link:http://bashdb.sourceforge.net/ruby-debug.html[Debugging with ruby-debug]
 * link:http://cheat.errtheblog.com/s/rdebug/[ruby-debug cheat sheet]
 * link:http://wiki.rubyonrails.org/rails/pages/HowtoConfigureLogging[Ruby on Rails Wiki: How to Configure Logging]
+* link:http://blog.evanweaver.com/files/doc/fauna/bleak_house/files/README.html[Bleak House Documentation]
 
 == Changelog ==
 
 http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/5[Lighthouse ticket]
 
+* November 3, 2008: Added RJS, memory leaks and plugins chapters by link:../authors.html#miloops[Emilio Tagua]
 * October 19, 2008: Copy editing pass by link:../authors.html#mgunderloy[Mike Gunderloy]
 * September 16, 2008: initial version by link:../authors.html#miloops[Emilio Tagua]