Rack middleware for tracing object allocations in Ruby 2.1
JavaScript Ruby CSS Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
demo_rack_apps
lib/rack
spec
.gitignore adding first demo Rack apps Oct 29, 2013
.travis.yml Adding a travis yaml, adjusting gems Jan 27, 2014
CHANGELOG.markdown
Gemfile
Gemfile.lock Merge branch 'master' of github.com:srawlins/rack-allocation_stats Feb 7, 2014
LICENSE
README.markdown
Rakefile yay js specs!!! Oct 28, 2013
TODO.markdown fixed some style Nov 2, 2013
basic-screen.gif
rack-allocation_stats.gemspec

README.markdown

Rack AllocationStats Build Status

Rack AllocationStats is a Rack Middleware, similar in design to rack-perftools_profiler, that will show information about object allocations that occurr during an HTTP request. The heart of Rack AllocationStats is the AllocationStats gem. Install Rack AllocationStats with Ruby 2.1 (newer than preview1) and:

  • Bundler: add gem 'rack-allocation_stats' to your Gemfile, or
  • RubyGems: run gem install rack-allocation_stats

Rack AllocationStats must also be included in your Rack application's middleware:

Rails:

# in your config/application.rb
config.middleware.use ::Rack::AllocationStats

Other Rack apps:

# in your rackup file
use Rack::AllocationStats

Summary

In order to trigger Rack AllocationStats, a parameter must be appended to the request URL: ras[trace]=true ('ras' for Rack AllocationStats). This will trace the object allocations that occur inside your Rack app during your request.

For example, if you have a Rack app that responds to the following request:

http://my.rack.app:9292/path?foo=bar

then you can just add &ras[trace]=true to activate Rack AllocationStats:

http://my.rack.app:9292/path?foo=bar&ras[trace]=true

Instead of the normal response that your app generates, Rack AllocationStats will respond with a tabular listing of allocation statistics.

Demonstration

There are additional paramters that you can attach to the request URL to change the response:

Help text

To see some help text on what options are available, use ras[trace]=true, and also add ras[help]. Rack AllocationStats will respond with man page-style help text.

Limit the file system scope

If you only wish to see allocations that originate from a certain directory, you can use the ras[scope] parameter. For example:

  • To limit the list of allocations to those with a sourcefile that includes yajl, append to the location:

    ?ras[trace]=true&ras[scope]=yajl
    
  • To limit the list of allocations to those in the present working directory. . is a special value for ras[scope] that is expanded to the full path of the present working directory, append to the location:

    ?ras[trace]=true&ras[scope]=.
    

Alias paths

In order to reduce the with of the sourcefile, you can add ras[alias_paths]=true, which will shorten paths in the following directories:

  • your present working directory (to be replaced with <PWD>)
  • Ruby's lib directory (to be replaced with <RUBYLIBDIR>)
  • the Gem directory, where installed gems live (eg: sqlite3-1.3.8 to be replaced with <GEM:sqlite3-1.3.8>)

Change the output

There are several values that you can pass with ras[output] parameter:

  • columnar is the default response output, displaying allocation groups in text columns.
  • json will respond with a JSON string representing all of the groups of allocations (by default grouped by sourcefile, sourceline, and object class).
  • interactive will respond with a JavaScript application that allows you to interactively tweak how you wish to group, arrange, and filter the traced allocations.

Request multiple times

If your Rack application appears to have some variability, you can use ras[times]=N to pass the request onto your Rack application N times. The response that Rack AllocationStats generates will contain all of the requests that occurred over the N requests.