airbnb-ruby-prof 0.0.1

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (C) 2005 - 2014 Shugo Maeda <shugo@ruby-lang.org> and Charlie Savage <cfis@savagexi.com>
+Copyright (C) 2010 - 2014 Stefan Kaes <skaes@railsepxress.de>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,426 @@
+= ruby-prof
+
+{<img src="https://travis-ci.org/ruby-prof/ruby-prof.png?branch=master" alt="Build Status" />}[https://travis-ci.org/ruby-prof/ruby-prof]
+
+== Overview
+
+ruby-prof is a fast code profiler for MRI Ruby.  Its features include:
+
+* Speed - it is a C extension and therefore many times faster than the standard Ruby profiler.
+* Modes - Ruby prof can measure a number of different parameters, including call times, memory usage and object allocations.
+* Reports - can generate text and cross-referenced html reports
+  - Flat Profiles - similar to the reports generated by the standard Ruby profiler
+  - Graph profiles - similar to GProf, these show how long a method runs, which methods call it and which methods it calls.
+  - Call tree profiles - outputs results in the calltree format suitable for the KCacheGrind profiling tool.
+  - Many more -- see reports section of this \README.
+* Threads - supports profiling multiple threads simultaneously
+
+== Requirements
+
+ruby-prof requires Ruby 1.9.3 or higher. Please note some ruby
+releases have known bugs which cause ruby-prof problems, like
+incorrect measurements. We suggest to use the latest minor patch level
+release if possible. In particular, on the 2.1 branch of ruby you
+should use at least 2.1.7.
+
+If you are running Linux or Unix you'll need a C compiler so the
+extension can be compiled when it is installed.
+
+If you are running Windows, then you may need to install the
+Windows specific RubyGem which includes an already built extension (see Install section).
+
+== Install
+
+The easiest way to install ruby-prof is by using Ruby Gems.  To
+install:
+
+    gem install ruby-prof
+
+If you're on windows then please install the devkit first so that it
+can compile.
+
+== Usage
+
+There are three major options for running ruby-prof: via the command
+line, via its convenience API or via its core API.
+
+=== ruby-prof Executable
+
+The first is to use ruby-prof to run the Ruby program you want to
+profile.  For more information refer to the documentation of the
+ruby-prof command.
+
+
+=== ruby-prof Convenience API
+
+The second way is to use the ruby-prof convenience API to profile
+particular segments of code.
+
+    require 'ruby-prof'
+
+    # profile the code
+    RubyProf.start
+    # ... code to profile ...
+    result = RubyProf.stop
+
+    # print a flat profile to text
+    printer = RubyProf::FlatPrinter.new(result)
+    printer.print(STDOUT)
+
+Alternatively, you can use a block to tell ruby-prof what to profile:
+
+    require 'ruby-prof'
+
+    # profile the code
+    result = RubyProf.profile do
+      # ... code to profile ...
+    end
+
+    # print a graph profile to text
+    printer = RubyProf::GraphPrinter.new(result)
+    printer.print(STDOUT, {})
+
+ruby-prof also supports pausing and resuming profiling runs.
+
+    require 'ruby-prof'
+
+    # profile the code
+    RubyProf.start
+    # ... code to profile ...
+
+    RubyProf.pause
+    # ... other code ...
+
+    RubyProf.resume
+    # ... code to profile ...
+    result = RubyProf.stop
+
+Note that resume will only work if start has been called previously.
+In addition, resume can also take a block:
+
+    require 'ruby-prof'
+
+    RubyProf.resume do
+      # ... code to profile...
+    end
+
+    result = RubyProf.stop
+
+With this usage, resume will automatically call pause at the
+end of the block.
+
+=== Profiling Selected Threads (Core API)
+
+The convenience API does not support running multiple profiles in
+separate threads concurrently, but the RubyProf::Profile API does. In
+fact, the convenience layer uses the Profile API internally. It all
+revolves around Profile objects:
+
+RubyProf::Profile.new::
+   Create a profile object given an options hash (see below)
+
+   The following options are available when creating Profile instances:
+
+   measure_mode::
+       One of the defined measure modes
+
+   exclude_threads::
+       Array of threads which should not be profiled.
+
+   include_threads::
+       Array of threads which should be profiled. All other threads will
+       be ignored.
+
+   merge_fibers::
+       Whether profiling data for a given thread's fibers should all be
+       subsumed under a single entry. Basically only useful to produce
+       callgrind profiles.
+
+RubyProf::Profile#start::
+   Start profiling
+
+RubyProf::Profile#pause::
+   Pause profiling
+
+RubyProf::Profile#resume::
+   Resume profiling
+
+RubyProf::Profile#stop::
+   Stop profiling and return self
+
+RubyProf::Profile#profile::
+   Perform a profile run and return result. Accepts the same arguments
+   as RubyProf::Profile.new.
+
+== Profiling Rails
+
+To profile a Rails application it is vital to run it using production like
+settings (cache classes, cache view lookups, etc.).  Otherwise, Rail's
+dependency loading code will overwhelm any time spent in the application
+itself (our tests show that Rails dependency loading causes a roughly 6x
+slowdown).  The best way to do this is create a new Rails environment,
+profile.rb.
+
+So to profile Rails:
+
+1. Create a new profile.rb environment. Make sure to turn on
+   <tt>cache_classes</tt> and
+   <tt>cache_template_loading</tt>. Otherwise your profiling results
+   will be overwhelmed by the time Rails spends loading required
+   files. You should likely turn off caching.
+
+2. Add the ruby-prof to your gemfile:
+
+    group :profile do
+      gem 'ruby-prof'
+    end
+
+3. Add the ruby prof rack adapter to your middleware stack.  One way to
+   do this is by adding the following code to <tt>config.ru</tt>:
+
+    if Rails.env.profile?
+      use Rack::RubyProf, :path => '/temp/profile'
+    end
+
+   The path is where you want profiling results to be stored.  By default the
+   rack adapter will generate a html call graph report and flat text report.
+
+4. Now make a request to your running server.  New profiling
+   information will be generated for each request.  Note that each
+   request will overwrite the profiling reports created by the
+   previous request!
+
+== Reports
+
+ruby-prof can generate a number of different reports:
+
+* Flat Reports
+* Graph Reports
+* HTML Graph Reports
+* Call graphs
+* Call stack reports
+* More!
+
+Flat profiles show the overall time spent in each method. They
+are a good way of quickly identifying which methods take the most time.
+An example of a flat profile and an explanation can be found in
+{examples/flat.txt}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/flat.txt].
+
+There are several varieties of these - run <tt>ruby-prof --help</tt>
+
+Graph profiles also show the overall time spent in each method. In
+addition, they also show which methods call the current method and which
+methods its calls.  Thus they are good for understanding how methods
+gets called and provide insight into the flow of your program. An
+example text graph profile is located at
+{examples/graph.txt}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.txt].
+
+HTML Graph profiles are the same as graph profiles, except output is
+generated in hyper-linked HTML. Since graph profiles can be quite large,
+the embedded links make it much easier to navigate the results. An
+example html graph profile is located at
+{examples/graph.html}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/graph.html].
+
+Call graphs output results in the calltree profile format which is used
+by KCachegrind. Call graph support was generously donated by Carl
+Shimer. More information about the format can be found at the
+{KCachegrind}[http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindCalltreeFormat]
+site.
+
+Call stack reports produce a HTML visualization of the time spent in
+each execution path of the profiled code. An example can be found at
+{examples/stack.html}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/stack.html].
+
+Another good example: http://twitpic.com/28z94a
+
+Finally, there's a so called MultiPrinter which can generate several
+reports in one profiling run. See
+{examples/multi.stack.html}[http://github.com/ruby-prof/ruby-prof/tree/master/examples/multi.stack.html].
+
+There is also a graphviz .dot visualiser.
+
+== Printers
+
+Reports are created by printers.  Supported printers include:
+
+RubyProf::FlatPrinter::
+  Creates a flat report in text format
+
+RubyProf::FlatPrinterWithLineNumbers::
+  Same as above but more verbose
+
+RubyProf::GraphPrinter::
+  Creates a call graph report in text format
+
+RubyProf::GraphHtmlPrinter::
+  Creates a call graph report in HTML (separate files per thread)
+
+RubyProf::DotPrinter::
+  Creates a call graph report in GraphViz's DOT format which can be converted to an image
+
+RubyProf::CallTreePrinter::
+  Creates a call tree report compatible with KCachegrind
+
+RubyProf::CallStackPrinter::
+  Creates a HTML visualization of the Ruby stack
+
+RubyProf::MultiPrinter::
+  Uses the other printers to create several reports in one profiling run
+
+To use a printer:
+
+    result = RubyProf.stop
+    printer = RubyProf::GraphPrinter.new(result)
+    printer.print(STDOUT, :min_percent => 2)
+
+
+The first parameter is any writable IO object such as <tt>STDOUT</tt>
+or a file.  The second parameter, specifies the minimum percentage a
+method must take to be printed.  Percentages should be specified as
+integers in the range 0 to 100.  For more information please see the
+documentation for the different printers.
+
+The other option is <tt>:print_file => true</tt> (default false),
+which adds the filename to the output (GraphPrinter only).
+
+<tt>MultiPrinter</tt> differs from the other printers in that it
+requires a directory path and a basename for the files it produces.
+
+    printer = RubyProf::MultiPrinter.new(result)
+    printer.print(:path => ".", :profile => "profile")
+
+== Measurements
+
+Depending on the mode and platform, ruby-prof can measure various
+aspects of a Ruby program. Supported measurements include:
+
+RubyProf::WALL_TIME::
+  Wall time measures the real-world time
+  elapsed between any two moments.  If there are other processes
+  concurrently running on the system that use significant CPU or disk
+  time during a profiling run then the reported results will be larger
+  than expected.
+
+RubyProf::PROCESS_TIME::
+  Process time measures the time used by a process between any two moments.
+  It is unaffected by other processes concurrently running
+  on the system. Note that Windows does not support measuring process
+  times.
+
+RubyProf::CPU_TIME::
+  CPU time uses the CPU clock counter to measure time.  The returned
+  values are dependent on the correctly setting the CPU's frequency.
+  This mode is only supported on Pentium or PowerPC platforms (linux only).
+
+RubyProf::ALLOCATIONS::
+  Object allocation reports show how many objects each method in
+  a program allocates.  This support was added by Sylvain Joyeux
+  and requires a patched Ruby interpreter. See below.
+
+
+RubyProf::MEMORY::
+  Memory usage reports show how much memory each method in a program
+  uses.  This support was added by Alexander Dymo and requires a
+  patched Ruby interpreter. See below.
+
+RubyProf::GC_TIME::
+  Garbage collection time reports how much time is spent in Ruby's
+  garbage collector during a profiling session. This support was added
+  by Jeremy Kemper and requires a patched Ruby interpreter. See below.
+
+RubyProf::GC_RUNS::
+ Garbage collection runs report how many times Ruby's garbage collector
+ is invoked during a profiling session. This support was added by
+ Jeremy Kemper and requires a patched Ruby interpreter. See below.
+
+== Patching ruby
+
+All of the patches to Ruby are included in the railsexpress patchsets
+for rvm, see https://github.com/skaes/rvm-patchsets. You can also use
+these patches manually with other ruby managers (ruby-install, 
+ruby-build, etc.).
+
+Note if you rebuild your ruby with patches you must uninstall and
+reinstall the ruby-prof gem to take advantage of the new capabilities.
+
+== Measure modes
+
+To set the measurement:
+
+    RubyProf.measure_mode = RubyProf::WALL_TIME
+    RubyProf.measure_mode = RubyProf::PROCESS_TIME
+    RubyProf.measure_mode = RubyProf::CPU_TIME
+    RubyProf.measure_mode = RubyProf::ALLOCATIONS
+    RubyProf.measure_mode = RubyProf::MEMORY
+    RubyProf.measure_mode = RubyProf::GC_TIME
+    RubyProf.measure_mode = RubyProf::GC_RUNS
+
+The default value is <tt>RubyProf::WALL_TIME</tt>.
+
+You may also specify the measure mode by using the
+<tt>RUBY_PROF_MEASURE_MODE</tt> environment variable:
+
+    export RUBY_PROF_MEASURE_MODE=wall
+    export RUBY_PROF_MEASURE_MODE=process
+    export RUBY_PROF_MEASURE_MODE=cpu
+    export RUBY_PROF_MEASURE_MODE=allocations
+    export RUBY_PROF_MEASURE_MODE=memory
+    export RUBY_PROF_MEASURE_MODE=gc_time
+    export RUBY_PROF_MEASURE_MODE=gc_runs
+
+On Linux, process time is measured using the clock method provided
+by the C runtime library. Note that the clock method does not
+report time spent in the kernel or child processes and therefore
+does not measure time spent in methods such as Kernel.sleep method.
+If you need to measure these values, then use wall time.  Wall time
+is measured using the gettimeofday kernel method.
+
+If you set the clock mode to <tt>PROCESS_TIME</tt>, then timings are
+read using the clock method provided by the C runtime library.  Note
+though, these values are wall times on Windows and not process times
+like on Linux.  Wall time is measured using the GetLocalTime API.
+
+If you use wall time, the results will be affected by other
+processes running on your computer, network delays, disk access,
+etc.  As result, for the best results, try to make sure your
+computer is only performing your profiling run and is
+otherwise quiescent.
+
+== Multi-threaded Applications
+
+Unfortunately, Ruby does not provide an internal API for detecting
+thread context switches.  As a result, the timings ruby-prof reports
+for each thread may be slightly inaccurate.  In particular, this will
+happen for newly spawned threads that go to sleep immediately (their
+first call).  For instance, if you use Ruby's timeout library to wait
+for 2 seconds, the 2 seconds will be assigned to the foreground thread
+and not the newly created background thread.  These errors can largely
+be avoided if the background thread performs any operation before
+going to sleep.
+
+== Performance
+
+Significant effort has been put into reducing ruby-prof's overhead
+as much as possible.  Our tests show that the overhead associated
+with profiling code varies considerably with the code being
+profiled.  Most programs will run approximately twice as slow
+while highly recursive programs (like the fibonacci series test)
+will run three times slower.
+
+== License
+
+See LICENSE for license information.
+
+== API Documentation
+
+The ruby-prof API documentation for the latest released gem version
+can be found here: http://www.rubydoc.info/gems/ruby-prof/
+
+The ruby-prof API documentation for the master branch is available
+here: http://www.rubydoc.info/github/ruby-prof/ruby-prof/
+
+== Development
+
+Code is located at https://github.com/ruby-prof/ruby-prof
+
+Google group/mailing list: http://groups.google.com/group/ruby-optimization or open a github issue.