From 807c1e899d48e97318df7aab901cc1c1ee927292 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sat, 10 Jan 2009 03:28:23 +0000 Subject: Minor changes in performance guide --- railties/doc/guides/html/index.html | 2 +- railties/doc/guides/html/performance_testing.html | 61 +++++++++++++--------- railties/doc/guides/source/index.txt | 2 +- railties/doc/guides/source/performance_testing.txt | 60 ++++++++++++--------- 4 files changed, 72 insertions(+), 53 deletions(-) (limited to 'railties/doc/guides') 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.

-
Performance testing Rails Applications
+
Performance Testing Rails Applications
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 --> -
[lifo@null application (master)]$ script/generate performance_test homepage
-

This will generate test/performance/homepage_test.rb:

+
script/generate performance_test homepage
+

This generates homepage_test.rb inside test/performance directory:

get '/' end end
-

Which you can modify to suit your needs.

1.2. Examples

-

Let’s assume your application have the following controller and model:

+

Let’s assume your application has the following controller and model:

end

You can find more details about get and post methods in API documentation of integration testing.

1.2.2. Model Example

-

Even though performance tests are integration tests and hence closer to request/response cycle by nature, it doesn’t prevent us from testing pure model code inside. Performance test for Post model above can be somewhat like:

+

Even though the performance tests are integration tests and hence closer to request/response cycle by nature, it doesn’t prevent us from performance testing pure model code.

+

Performance test for Post model:

end end

1.3. Modes

-

Performance test cases can be run in two modes : Benchmarking and Profling.

+

Performance tests can be run in two modes : Benchmarking and Profling.

1.3.1. Benchmarking

-

Benchmarking helps you find out how fast are your test cases. Each Test case is run 4 times in this mode. To run performance tests in benchmarking mode:

+

Benchmarking helps find out how fast is a performance test. Each test case is run 4 times in benchmarking mode.

+

To run performance tests in benchmarking mode:

$ rake test:benchmark

1.3.2. Profiling

-

Profiling helps introspect into your test cases and figure out which are the slow parts. Each Test case is run 1 time in this mode. To run performance tests in profiling mode:

+

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 1 time in profiling mode.

+

To run performance tests in profiling mode:

$ rake test:profile

1.4. Metrics

-

Benchmarking and profiling run performance test cases in various modes to help precisely figure out the where the problem lies.

+

Benchmarking and profiling run performance tests in various modes described below.

1.4.1. Wall Time

Measures the real world time elapsed during the test run. It is affected by any other processes concurrently running on the system.

Mode : Benchmarking

@@ -464,7 +466,7 @@ http://www.gnu.org/software/src-highlite --> gc_runs: 0 gc_time: 19 ms
CSV files
-

Performance tests results are also appended to .csv files inside tmp/performance/<Class>#<test>_<metric>.csv file. For example, running the default BrowsingTest#test_homepage will generate following five files :

+

Performance test results are also appended to .csv files inside tmp/performance. For example, running the default BrowsingTest#test_homepage will generate following five files :

  • @@ -492,8 +494,8 @@ BrowsingTest#test_homepage_wall_time.csv

-

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.

-

Sample output of +BrowsingTest#test_homepage_wall_time.csv + :

+

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.

+

Sample output of BrowsingTest#test_homepage_wall_time.csv:

0.00771250000000012,2009-01-09T15:46:03Z,,2.3.0.master.859e150,ruby-1.8.6.110,i686-darwin9.0.0

1.5.2. Profiling

Command line
-

This is the very basic form of output in profiling mode. Example :

+

This is a very basic form of output in profiling mode. Example :

Tree

Tree output is profiling information in calltree format for use by kcachegrind and similar tools.

1.6. Installing GC Patched Ruby

-

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’ve never compiled a Ruby binary before, you can follow the following steps to build a ruby binary inside your home directory:

+

To get the best from Rails performance tests, you need to build a special Ruby binary with some super powers - GC patch for measuring GC Runs/Time and memory/object allocation.

+

The process is fairly straight forward. If you’ve never compiled a Ruby binary before, follow the following steps to build a ruby binary inside your home directory:

1.6.1. Instllation

Compile Ruby and apply this GC Patch:

1.6.2. Download and Extract

@@ -559,7 +562,7 @@ http://www.gnu.org/software/src-highlite --> 
[lifo@null ruby-version]$ ./configure --prefix=/<homedir>/rubygc
 [lifo@null ruby-version]$ make && make install

1.6.5. Prepare aliases

-

For convenience, add the following lines in your ~/.profile after replacing <username> with your :

+

For convenience, add the following lines in your ~/.profile:

alias gcruby='~/rubygc/bin/ruby'
@@ -568,7 +571,7 @@ alias gcgem='~/rubygc/bin/gem'
 alias gcirb='~/rubygc/bin/irb'
 alias gcrails='~/rubygc/bin/rails'
-

1.6.6. Install rubygems and some basic gems

+

1.6.6. Install rubygems and dependency gems

Download Rubygems and install it from source. Rubygem’s README file should have necessary installation instructions.

Additionally, installa the following gems :

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

And you’re ready to go. Don’t forget to use gcruby and gcrake aliases when running performance tests!

+

And you’re ready to go. Don’t forget to use gcruby and gcrake aliases when running the performance tests.

2. Helper methods

-

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 benchmark() in all three components.

+

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 benchmark() in all the three components.

2.1. Model

project.create_manager("name" => "David") project.milestones << Milestone.find(:all) end
-

The above code benchmarks the multiple statments enclosed inside Project.benchmark("Creating project") do..end block and prints the results to the log file. The statement inside log files will look like:

+

This benchmarks the code enclosed in Project.benchmark("Creating project") do..end block and prints the result to the log file:

Creating projectem (185.3ms)

Please refer to API docs for optional options to benchmark()

2.2. Controller

-

Similarly, you could use this helper method inside controllers ( Note that it’s a class method here ):

+

Similarly, you could use this helper method inside controllers

+
+ + + +
+Note +benchmark it’s a class method inside controllers.
+

3. Request Logging

-

Rails log files containt basic but very useful information about the time taken to serve each request. A typical log entry looks something like :

+

Rails log files containt very useful information about the time taken to serve each request. Here’s a typical log file entry:

Rendering template within layouts/items Rendering items/index Completed in 5ms (View: 2, DB: 0) | 200 OK [http://0.0.0.0/items]
-

For this section, we’re only interested in the last line from that log entry:

+

For this section, we’re only interested in the last line:

  • -January 9, 2009: Rewrite by Pratik +January 9, 2009: Complete rewrite by Pratik

  • diff --git a/railties/doc/guides/source/index.txt b/railties/doc/guides/source/index.txt index 130beedf08..61be44c63e 100644 --- a/railties/doc/guides/source/index.txt +++ b/railties/doc/guides/source/index.txt @@ -113,7 +113,7 @@ ways of achieving this and how to understand what is happening "behind the scene of your code. *********************************************************** -.link:performance_testing.html[Performance testing Rails Applications] +.link:performance_testing.html[Performance Testing Rails Applications] *********************************************************** CAUTION: link:http://rails.lighthouseapp.com/projects/16213/tickets/4[Lighthouse Ticket] diff --git a/railties/doc/guides/source/performance_testing.txt b/railties/doc/guides/source/performance_testing.txt index e58927b758..a21f323f2f 100644 --- a/railties/doc/guides/source/performance_testing.txt +++ b/railties/doc/guides/source/performance_testing.txt @@ -38,10 +38,10 @@ Rails provides a generator called +performance_test+ for creating new performanc [source, shell] ---------------------------------------------------------------------------- -[lifo@null application (master)]$ script/generate performance_test homepage +script/generate performance_test homepage ---------------------------------------------------------------------------- -This will generate +test/performance/homepage_test.rb+: +This generates +homepage_test.rb+ inside +test/performance+ directory: [source, ruby] ---------------------------------------------------------------------------- @@ -56,11 +56,9 @@ class HomepageTest < ActionController::PerformanceTest end ---------------------------------------------------------------------------- -Which you can modify to suit your needs. - === Examples === -Let's assume your application have the following controller and model: +Let's assume your application has the following controller and model: [source, ruby] ---------------------------------------------------------------------------- @@ -102,9 +100,9 @@ end ==== Controller Example ==== -Performance tests are special kind of integration tests. This allows you to use +get+ and +post+ methods inside the performance tests. +Performance tests are a special kind of integration tests. This allows you to use +get+ and +post+ methods inside the performance tests. -Performance tests for the controller code above can be something like: +Here's the performance test for +HomeController#dashboard+ and +PostsController#create+: [source, ruby] ---------------------------------------------------------------------------- @@ -131,7 +129,9 @@ You can find more details about +get+ and +post+ methods in API documentation of ==== Model Example ==== -Even though performance tests are integration tests and hence closer to request/response cycle by nature, it doesn't prevent us from testing pure model code inside. Performance test for +Post+ model above can be somewhat like: +Even though the performance tests are integration tests and hence closer to request/response cycle by nature, it doesn't prevent us from performance testing pure model code. + +Performance test for +Post+ model: [source, ruby] ---------------------------------------------------------------------------- @@ -152,11 +152,13 @@ end === Modes === -Performance test cases can be run in two modes : Benchmarking and Profling. +Performance tests can be run in two modes : Benchmarking and Profling. ==== Benchmarking ==== -Benchmarking helps you find out how fast are your test cases. Each Test case is run +4 times+ in this mode. To run performance tests in benchmarking mode: +Benchmarking helps find out how fast is a performance test. Each test case is run +4 times+ in benchmarking mode. + +To run performance tests in benchmarking mode: [source, shell] ---------------------------------------------------------------------------- @@ -165,7 +167,9 @@ $ rake test:benchmark ==== Profiling ==== -Profiling helps introspect into your test cases and figure out which are the slow parts. Each Test case is run +1 time+ in this mode. To run performance tests in profiling mode: +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 +1 time+ in profiling mode. + +To run performance tests in profiling mode: [source, shell] ---------------------------------------------------------------------------- @@ -174,7 +178,7 @@ $ rake test:profile === Metrics === -Benchmarking and profiling run performance test cases in various modes to help precisely figure out the where the problem lies. +Benchmarking and profiling run performance tests in various modes described below. ==== Wall Time ==== @@ -236,7 +240,7 @@ BrowsingTest#test_homepage (31 ms warmup) ===== CSV files ===== -Performance tests results are also appended to +.csv+ files inside +tmp/performance/#_.csv+ file. For example, running the default +BrowsingTest#test_homepage+ will generate following five files : +Performance test results are also appended to +.csv+ files inside +tmp/performance+. For example, running the default +BrowsingTest#test_homepage+ will generate following five files : - BrowsingTest#test_homepage_gc_runs.csv - BrowsingTest#test_homepage_gc_time.csv @@ -244,9 +248,9 @@ Performance tests results are also appended to +.csv+ files inside +tmp/performa - BrowsingTest#test_homepage_objects.csv - BrowsingTest#test_homepage_wall_time.csv -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. +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. -Sample output of +BrowsingTest#test_homepage_wall_time.csv + : +Sample output of +BrowsingTest#test_homepage_wall_time.csv+: [source, shell] ---------------------------------------------------------------------------- @@ -267,7 +271,7 @@ measurement,created_at,app,rails,ruby,platform ===== Command line ===== -This is the very basic form of output in profiling mode. Example : +This is a very basic form of output in profiling mode. Example : [source, shell] ---------------------------------------------------------------------------- @@ -292,7 +296,9 @@ Tree output is profiling information in calltree format for use by kcachegrind a [[gc]] === Installing GC Patched Ruby === -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've never compiled a Ruby binary before, you can follow the following steps to build a ruby binary inside your home directory: +To get the best from Rails performance tests, you need to build a special Ruby binary with some super powers - http://rubyforge.org/tracker/download.php/1814/7062/17676/3291/ruby186gc.patch[GC patch] for measuring GC Runs/Time and memory/object allocation. + +The process is fairly straight forward. If you've never compiled a Ruby binary before, follow the following steps to build a ruby binary inside your home directory: ==== Instllation ==== @@ -327,7 +333,7 @@ The following will install ruby in your home directory's +/rubygc+ directory. Ma ==== Prepare aliases ==== -For convenience, add the following lines in your ~/.profile after replacing with your : +For convenience, add the following lines in your +~/.profile+: ---------------------------------------------------------------------------- alias gcruby='~/rubygc/bin/ruby' @@ -337,7 +343,7 @@ alias gcirb='~/rubygc/bin/irb' alias gcrails='~/rubygc/bin/rails' ---------------------------------------------------------------------------- -==== Install rubygems and some basic gems ==== +==== Install rubygems and dependency gems ==== Download http://rubyforge.org/projects/rubygems[Rubygems] and install it from source. Rubygem's README file should have necessary installation instructions. @@ -356,11 +362,11 @@ If installing +mysql+ fails, you can try to install it manually: [lifo@null mysql]$ make && make install ---------------------------------------------------------------------------- -And you're ready to go. Don't forget to use +gcruby+ and +gcrake+ aliases when running performance tests! +And you're ready to go. Don't forget to use +gcruby+ and +gcrake+ aliases when running the performance tests. == Helper methods == -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 +benchmark()+ in all three components. +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 +benchmark()+ in all the three components. === Model === @@ -373,7 +379,7 @@ Project.benchmark("Creating project") do end ---------------------------------------------------------------------------- -The above code benchmarks the multiple statments enclosed inside +Project.benchmark("Creating project") do..end+ block and prints the results to the log file. The statement inside log files will look like: +This benchmarks the code enclosed in +Project.benchmark("Creating project") do..end+ block and prints the result to the log file: [source, ruby] ---------------------------------------------------------------------------- @@ -384,7 +390,9 @@ Please refer to http://api.rubyonrails.com/classes/ActiveRecord/Base.html#M00133 === Controller === -Similarly, you could use this helper method inside http://api.rubyonrails.com/classes/ActionController/Benchmarking/ClassMethods.html#M000715[controllers] ( Note that it's a class method here ): +Similarly, you could use this helper method inside http://api.rubyonrails.com/classes/ActionController/Benchmarking/ClassMethods.html#M000715[controllers] + +NOTE: +benchmark+ it's a class method inside controllers. [source, ruby] ---------------------------------------------------------------------------- @@ -409,7 +417,7 @@ And in http://api.rubyonrails.com/classes/ActionController/Benchmarking/ClassMet == Request Logging == -Rails log files containt basic but very useful information about the time taken to serve each request. A typical log entry looks something like : +Rails log files containt very useful information about the time taken to serve each request. Here's a typical log file entry: [source, ruby] ---------------------------------------------------------------------------- @@ -419,7 +427,7 @@ Rendering items/index Completed in 5ms (View: 2, DB: 0) | 200 OK [http://0.0.0.0/items] ---------------------------------------------------------------------------- -For this section, we're only interested in the last line from that log entry: +For this section, we're only interested in the last line: [source, ruby] ---------------------------------------------------------------------------- @@ -448,6 +456,6 @@ Rails has been lucky to have three startups dedicated to Rails specific performa http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/4[Lighthouse ticket] -* January 9, 2009: Rewrite by Pratik +* January 9, 2009: Complete rewrite by Pratik * October 17, 2008: First revision by Pratik * September 6, 2008: Initial version by Matthew Bergman -- cgit v1.2.3