active-profiling

= ActiveProfiling

ActiveProfiling is a gem I've slapped together over the years to help with profiling Rails applications.

== Profiler ActionController Filters

=== +action_profiler+

This filter wraps up the functionality of RubyProf for each action and can be used to spit out the results to +stdout+, your log file or to files in the +Rails.root/log/profiling+ directory.

Options and their defaults for +action_profiler+ are listed in ActiveProfiling::Railtie::DEFAULT_PROFILER_OPTIONS, but the gist of it is that you can basically use any of RubyProf's various options and control where the output is directed. For some the +:call_tree+ output type, results are written to individual files in +Rails.root/log/profiling+, while for all other output types the results are written to the Rails log. You can of course redirect all logging to files if you prefer, or to the standard output.

To enable this filter, add the following to your application configuration:

config.active_profiling.profiler.enabled = true

Additional configuration options can be found in the documentation for ActiveProfiling::Railtie.

=== +action_gc_statistics+

This filter wraps up the functionality of either GC::Profiler in Ruby 1.9+ or the GC statistics patches available for 1.8.7 if installed, either through Ruby Enterprise Edition or by patching your own Ruby. When enabled, information on the Ruby garbage collector will be written to the Rails log at the end of each action response. Options for controlling how the information is collected and logged can be found in ActiveProfiling::Railtie::DEFAULT_GC_STATISTICS_OPTIONS.

Note that the output for Ruby 1.9+ is a bit different from REE or a patched Ruby due to the manner in which they collect and report on GC statistics. In the REE patches you can access a number of options that aren't currently available in GC::Profiler. I've tried to make some sensible output for REE, but there are going to be differences based solely on the manner in which the statistics are collected.

To enable this filter, add the following to your application configuration:

config.active_profiling.gc_statistics.enabled = true

Additional configuration options can be found in the documentation for ActiveProfiling::Railtie.

== Profiling Blocks

You can also profile individual blocks of code by using the ActiveProfiling.ruby_profiler and ActiveProfiling.gc_statistics methods or by including the ActiveProfiling::RubyProfiler or ActiveProfiling::GCStatistics modules and using the methods in your own classes and modules. In both cases, these methods take the same options as found in the ActionController filters minus the +:enabled+ option.

Will spit out the GC statistics if GC is run, same as with the action

filter.

ActiveProfiling.gc_statistics do # ... end

Wraps the block in a RubyProf session and logs the results accordingly.

ActiveProfiling.ruby_profiler(options) do # ... end

== Extended ActiveRecord Logging

The database can often be a performance hotspot, and tracking down where and why some queries are occuring in your application can be a pain. ActiveProfiling includes an extended query logger that can be configured to log backtraces for SQL queries that can help you track down where unexpected queries are occuring in your code.

To enable extended logging, add the following to your application configuration:

config.active_profiling.active_record.backtrace_logger.enabled = true

Additional configuration options can be found in the documentation for ActiveProfiling::Railtie.

== Using In A Rails Project

Profiling should be performed in a production environment, as profiling in development really isn't reflective of how your application is actually going to be running in the Real World. At the same time, you don't necessarily want to clutter up your application settings and +Gemfile+ with unnecessary code and have to worry about accidentally committing profiling settings to your source code repository and the like.

A semi-neat trick to try is to set up a file for local application settings thusly:

First, add the following to your +application.rb+. You generally want this near the end of the file.

if File.exists?("#{Rails.root}/config/application_local.rb") require "#{Rails.root}/config/application_local.rb" end

Add an entry for +application_local.rb+ to your +.gitignore+ file or otherwise ignore it with your SCM.

In +application_local.rb+, you can set up additional application settings like so:

You can now flip this line on and off to enable or disable

ActiveProfiling.

Bundler.require(:profiling, Rails.env) if defined?(Bundler)

module FooBarApp class Application < Rails::Application # config.log_level = :debug

  if defined?(ActiveProfiling)
    config.active_profiling.profiler.enabled = false
    config.active_profiling.profiler.output = :file
    config.active_profiling.profiler.printer = :graph_html
    config.active_profiling.profiler.printer_options = {
      :min_percent => 1,
      :print_file => true
    }
    config.active_profiling.gc_statistics.enabled = true

    config.active_profiling.active_record.backtrace_logger.enabled = true
  end

  # etc...
end

end

This allows you to tweak some settings without affecting your main +application.rb+ file.

You'll also want to add the following to your +Gemfile+:

group :profiling do gem 'active-profiling' gem 'ruby-prof' end

== License

This gem is licensed under an MIT-style license. See the +MIT-LICENSE+ file for details.