google-perftools for ruby code
Switch branches/tags
Nothing to show
Pull request Compare This branch is 72 commits behind tmm1:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


google-perftools for ruby code
  (c) 2009 Aman Gupta (tmm1)

=== Usage

  Run the profiler with a block:

    require 'perftools'
    PerfTools::CpuProfiler.start("/tmp/add_numbers_profile") do
      5_000_000.times{ 1+2+3+4+5 }

  Start and stop the profiler manually:

    require 'perftools'
    5_000_000.times{ 1+2+3+4+5 }

  Profile an existing ruby application without modifying it:

    $ CPUPROFILE=/tmp/my_app_profile RUBYOPT="-r`gem which perftools | tail -1`" ruby my_app.rb

  Change the sampling interval (defaults to 100 times a second, valid range is 1-4000):

    $ CPUPROFILE_FREQUENCY=500 ruby my_app.rb

  Use walltime instead of cputime profiling:

    $ CPUPROFILE_REALTIME=1 ruby my_app.rb

  Profile object allocations instead of cpu/wall time:

    $ CPUPROFILE_OBJECTS=1 ruby my_app.rb

=== Reporting

  pprof.rb --text /tmp/add_numbers_profile

  pprof.rb --pdf /tmp/add_numbers_profile > /tmp/add_numbers_profile.pdf

  pprof.rb --gif /tmp/add_numbers_profile > /tmp/add_numbers_profile.gif

  pprof.rb --callgrind /tmp/add_numbers_profile > /tmp/add_numbers_profile.grind
  kcachegrind /tmp/add_numbers_profile.grind

  pprof.rb --gif --focus=Integer /tmp/add_numbers_profile > /tmp/add_numbers_custom.gif

  pprof.rb --text --ignore=Gem /tmp/my_app_profile

  For more options, see

=== Examples

  pprof.rb --text

    Total: 1735 samples
        1487  85.7%  85.7%     1735 100.0% Integer#times
         248  14.3% 100.0%      248  14.3% Fixnum#+

  pprof.rb --gif

    Simple require 'rubygems' profile

    Comparing redis-rb with and without SystemTimer based socket timeouts

    Sinatra vs. Merb vs. Rails

    C-level profile of EventMachine + epoll + Ruby threads

    C-level profile of the ruby interpreter
      12% time spent in re_match_exec because of excessive calls to rb_str_sub_bang by Date.parse
      easily fixed by using the ThirdBase gem

=== Installation

  Just install the gem, which will download, patch and compile google-perftools for you:

    sudo gem install perftools.rb

  Or use the dev gem from github:

    gem install -s tmm1-perftools.rb

  Or build your own gem:

    git clone git://
    cd perftools.rb
    gem build perftools.rb.gemspec
    gem install perftools.rb

  You'll also need graphviz to generate call graphs using dot:

    sudo port install graphviz     # osx
    sudo apt-get install graphviz  # debian/ubuntu

=== Advantages over ruby-prof

  Sampling profiler

    perftools samples your process using setitimer() so it can be used in production with minimal overhead.

=== Profiling the Ruby VM and C extensions

  To profile C code, download and build an unpatched perftools (libunwind or ./configure --enable-frame-pointers required on x86_64):

    tar zxvf google-perftools-1.3.tar.gz
    cd google-perftools-1.3

    ./configure --prefix=/opt
    sudo make install

    export LD_PRELOAD=/opt/lib/                 # for linux
    export DYLD_INSERT_LIBRARIES=/opt/lib/libprofiler.dylib   # for osx
    CPUPROFILE=/tmp/ruby_interpreter.profile ruby -e' 5_000_000.times{ "hello world" } '

    pprof `which ruby` --text /tmp/ruby_interpreter.profile

=== TODO

  * Add support for heap profiling to find memory leaks (PerfTools::HeapProfiler)
  * Allow both C and Ruby profiling
  * Add setter for the sampling interval

=== Resources

  GoRuCo 2009 Lightning Talk on perftools.rb at 21:52

  Ilya Grigorik's introduction to perftools.rb

  Google Perftools

  Analyzing profiles and interpreting different output formats