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/source/index.txt | 2 +- railties/doc/guides/source/performance_testing.txt | 60 ++++++++++++---------- 2 files changed, 35 insertions(+), 27 deletions(-) (limited to 'railties/doc/guides/source') 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