configure do
use ::Rack::PerftoolsProfiler, :default_printer => 'gif'
end

For Rack::Builder, call use inside the Builder constructor block

Rack::Builder.new do
use ::Rack::PerftoolsProfiler, :default_printer => 'gif'
end

Options

:default_printer - can be set to 'text', 'gif', or 'pdf'. Default is 'text'.

:mode - can be set to 'cputime', 'methods', 'objects', 'walltime'. Default is :cputime. See the 'Profiling Modes' section below.

:frequency - in :cputime mode, the number of times per second the app will be sampled. Default is 100 (times/sec).

:bundler - run the profiler binary using 'bundle' if set to true. Default is false.

:gemfile_dir - directory with Gemfile. Default is the current directory.

:password - password-protect profiling.

Usage

There are two ways to profile your app: with a single request or with multiple requests.

To profile with a single request, visit the URL you want to profile, but add the profile and (optionally) the times GET params (which will rerun the action the specified number of times).

Example:

curl http://localhost:3000/foobar?profile=true&times=3

Note that this will change the status, body, and headers of the response (you'll get
back the profiling data, NOT the original response).

You can also profile your application using multiple requests. When you profile using this method, all responses are normal. You must visit __stop__ to complete profiling and then you can view the profiling data by visiting __data__.

Profiling Data Options

Regardless of how you profile your application, you can add additional params to change how the
data is displayed. When using a single request, these params are just added to the URL being profiled.
When using multiple requests, they are added to the __data__ URL.

In the default mode, there will be no profiling data for the 'slow' route, because it uses few CPU cycles (You'll see the message 'No nodes to print').

If you change the mode to :walltime, you'll get profiling data, since the call to sleep causes the code to spend several seconds of wall time in the block.

Overriding the Profiling mode

You can also switch the profiling mode on a per-request basis, but ONLY if you are switching to 'methods' or 'objects' mode. Due to the implementation of perftools.rb, it is NOT possible to switch to 'walltime' or 'cputime' modes.

To switch to another mode, provide the 'mode' option. When profiling with a single request, add the option to the URL profiled:

curl http://localhost:3000/foobar?profile=true&mode=objects

When profiling using multiple requests, add the option when visiting __start__ :

curl http://localhost:3000/__start__?mode=objects

If the 'mode' option is omitted, the middleware will default to the mode specified at configuration.

Profiling in production

It is recommended that you always profile your application in the 'production' environment (using rails server -e production or an equivalent), since there can be important differences between 'development' and 'production' that may affect performance.

However, it is recommended that you profile your application on a development or staging machine rather than on a production machine. This is because profiling with multiple requests will not work if your app is running in multiple Ruby server processes.

Profiling a single request will work if there are multiple server processes. If your staging machine is publicly accessible, you can password-protect single-request profiling by using the :password option and then using the profile GET parameter to provide the password:

curl http://localhost:3000/foobar?profile=PASSWORD

Changing behavior with environment variables

The mode and frequency settings are enabled by setting environment variables. Some of these environment variables must be set before 'perftools' is required. If you only require 'rack/perftools_profiler', it will do the right thing (require 'perftools' after setting the environment variables).

If you need to require 'perftools' before 'rack/perftools_profiler' (or you have other problems changing the mode or frequency), try using these environment variables yourself.

Setting the frequency:

CPUPROFILE_FREQUENCY=500 ruby your_app.rb

Setting the mode to 'wall time'

CPUPROFILE_REALTIME=1 ruby your_app.rb

Setting the mode to 'object allocation'

CPUPROFILE_OBJECTS=1 ruby your_app.rb

Acknowledgments

A huge thanks to Aman Gupta for the awesome perftools.rb gem.

The basic idea and initial implementation of the middleware was heavily influenced by Rack::Profiler from rack-contrib.

Notes on bugs

This project depends on the awesome perftools.rb gem. Before submitting a bug, please determine if the bug is with perftools.rb or with this middleware. For instance, if you are having a problem with installation, make sure gem install perftools.rb works. If it does not, please submit a bug report here.

Note on Patches/Pull Requests

Fork the project.

Make your feature addition or bug fix.

Add tests for it. This is important so I don't break it in a future version unintentionally.

Commit, do not mess with rakefile, version, or history (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull).