squaresquash / rails Goto Github PK

The Squash client library for Ruby on Rails projects.

License: Apache License 2.0

Ruby 100.00%

rails's Introduction

Squash Client Library: Ruby on Rails

This client library reports exceptions to Squash, the Squarish exception reporting and management system. It's compatible with both pure-Ruby and Ruby on Rails projects.

Documentation

Comprehensive documentation is written in YARD- and Markdown-formatted comments throughout the source. To view this documentation as an HTML site, run rake doc.

For an overview of the various components of Squash, see the website documentation at https://github.com/SquareSquash/web.

Compatibility

This library is compatible with Ruby 1.8.6 and later, including Ruby Enterprise Edition, and with Rails 2.0 and later.

Requirements

The only dependency is the squash_ruby gem and its dependencies. For more information, consult the squash_ruby gem documentation: https://github.com/SquareSquash/ruby

Usage

Add this gem and the Squash Ruby gem to your Gemfile:

gem 'squash_ruby', :require => 'squash/ruby'
gem 'squash_rails', :require => 'squash/rails'

See the squash_ruby gem for configuration instructions. Note that it is no longer necessary to set the :environment configuration option; the Rails client library automatically sets that to the Rails environment.

You can use the usual Squash::Ruby.notify method in your Rails projects, but you will miss out on some Rails-specific information in your exception logs. You can automatically have the Squash client send along request and Rails information by using the client's around_filter:

class ApplicationController < ActionController::Base
  include Squash::Ruby::ControllerMethods
  enable_squash_client
end

Now any exception raised in the course of processing a request will be annotated with Rails specific information. The exception is then re-raised for normal Rails exception handling.

There may be situations where other parts of the code "eat up" an exception before it reaches this filter; the most common example would be exceptions that are handled by a rescue_from statement elsewhere in your controller. You can use the {Squash::Ruby::ControllerMethods#notify_squash} method to still send these exceptions to Squash:

class ApplicationController < ActionController::Base
  include Squash::Ruby::ControllerMethods
  rescue_from(ActiveRecord::RecordInvalid) do |error|
    notify_squash error
    render :file => "public/422.html", :status => :unprocessable_entity
  end
end

Important note: Some versions of Rails (below 3.0) do not automatically run the rails/init.rb within the gem. You will need to call require 'squash/rails/configure' in a config/initializers file in order to apply the Rails configuration defaults. You'll also need to add load 'squash/rails/tasks.rake' to your Rakefile.

There are many additional features you can take advantage of; see Additional Features in the squash_ruby documentation.

Filtering Sensitive Information

By default, notify_squash uses the filtered parameter list generated according to your config.filter_parameters setting. If you need to further filter your request parameters, or if you are storing sensitive information in your session, headers, or other fields transmitted to Squash, override the {Squash::Ruby::ControllerMethods#filter_for_squash} method in your controller.

Deploys

Squash works best when you notify it if your web app's deploys. If you're using Capistrano, this is easy. For Capistrano 2, just add require 'squash/rails/capistrano2' to your config/deploy.rb file. Everything else should be taken care of. For Capistrano 3, just add require 'squash/rails/capistrano3' to your Capfile.

If you do not deploy to a live Git directory, you will need to write a REVISION file to your app root. To do this, include the following in your config/deploy.rb file in Capistrano 2 or 3:

before 'deploy:compile_assets', 'squash:write_revision'

or in Capistrano 2:

before 'deploy:assets:precompile', 'squash:write_revision'

If you're not using Capistrano, you will need to configure your deploy script so that it runs the squash:notify Rake task on every deploy target. This Rake task requires two environment variables to be set: REVISION (the current revision of the source code) and DEPLOY_ENV (the environment this server is hosting).

Additional Configuration Options

The Squash Rails gem adds the following configuration options:

deploy_path: The path to post new deploys to. By default it's set to /api/1.0/deploy.

rails's People

Contributors

Stargazers

Watchers

Forkers

sunnybit localshred devclan thefron thirst mlitwiniuk kdubel spin42 dominic0312 dondeng mejackreed mattbker pradylom shmargum stanneeru isabella232

rails's Issues

Where are the Squash::Ruby.configure statements supposed to be placed?

In an initializer?

Or in the environment config?

Configuration issues

Using Rails 3.2.12

initializer:

Squash::Ruby.configure api_host: 'https://myhost', api_key: 'myapikey'

Gemfile:

gem 'squash_ruby', :require => 'squash/ruby'
gem 'squash_rails', :require => 'squash/rails'

deploy.rb

require 'squash/rails/capistrano'

When running the squash:notify task I get this:

  * 2013-03-20 14:32:37 executing `squash:notify'
  * executing "cd /home/ubuntu/apps/myapp-rails/current && env RAILS_ENV=staging bundle exec rake squash:notify REVISION=5d0c23939c4ae27831b7c10f3ac35bf149613e79 DEPLOY_ENV=staging"
    servers: ["192.81.xx.xx"]
    [192.81.xx.xx] executing command
 ** [out :: 192.81.xx.xx] rake aborted!
 ** [out :: 192.81.xx.xx] 
 ** [out :: 192.81.xx.xx] undefined method `+' for nil:NilClass
 ** [out :: 192.81.xx.xx] 
 ** [out :: 192.81.xx.xx] /home/ubuntu/apps/myapp-rails/shared/bundle/ruby/2.0.0/gems/squash_ruby-1.1.1/lib/squash/ruby.rb:270:in `notify_deploy'
 ** [out :: 192.81.xx.xx] 
 ** [out :: 192.81.xx.xx] /home/ubuntu/apps/myapp-rails/shared/bundle/ruby/2.0.0/gems/squash_rails-1.1.0/lib/squash/rails/tasks.rake:21:in `block (2 levels) in <top (required)>'
 ** [out :: 192.81.xx.xx] 
 ** [out :: 192.81.xx.xx] Tasks: TOP => squash:notify
 ** [out :: 192.81.xx.xx] 
 ** [out :: 192.81.xx.xx] (See full trace by running task with --trace)
 ** [out :: 192.81.xx.xx]

When attempting to send an exception from console I get false:

irb(main):001:0> Squash::Ruby.notify(Exception.new("bad"))
=> false

And nothing appears in Squash web.

Ideas?

failsafe_errors appear to be silently eaten on Heroku

In my attempts to get this to work on heroku I've run into a problem in my client app and have narrowed it down to this area of squash/ruby: https://github.com/SquareSquash/ruby/blob/master/lib/squash/ruby.rb#L87

When I open up a heroku console to attempt to manually send a squash notification it doesn't appear to give me any feedback that something's gone wrong:

irb(main):001:0> err = nil
=> nil
irb(main):002:0> begin
irb(main):003:1*   raise "Something bad this way comes!"
irb(main):004:1> rescue Exception => e
irb(main):005:1>   err = e
irb(main):006:1>   Squash::Ruby.notify(e)
irb(main):007:1>   raise e
irb(main):008:1> end
RuntimeError: Something bad this way comes!
        from (irb):3
        from /app/vendor/bundle/ruby/1.9.1/gems/railties-3.2.11/lib/rails/commands/console.rb:47:in `start'
        from /app/vendor/bundle/ruby/1.9.1/gems/railties-3.2.11/lib/rails/commands/console.rb:8:in `start'
        from /app/vendor/bundle/ruby/1.9.1/gems/railties-3.2.11/lib/rails/commands.rb:41:in `<top (required)>'
        from script/rails:6:in `require'
        from script/rails:6:in `<main>'

(note that my squash app receives no hits to the api when tailing it's log)

Additionally, no feedback here (except a false return value):

irb(main):013:0> Squash::Ruby.notify(Exception.new("bad"))
=> false

I notice that if that notify method fails it may attempt to try to log to log/squash.failsafe.log which it won't be able to do because heroku is a readonly-filesystem, so then it should fall back to $stderr but it doesn't appear to be doing that either.

Digging deeper (specifically, to the exact line I linked to at the beginning of this issue) I notice I get an error when I run this command:

irb(main):028:0> hsh = Squash::Ruby.exception_info_hash(exception, Time.now, {}, nil)
RuntimeError: You must set the :revision_file configuration if the code is not running in a Git checkout
        from /app/vendor/bundle/ruby/1.9.1/gems/squash_ruby-1.0.1/lib/squash/ruby.rb:561:in `current_revision'
        from /app/vendor/bundle/ruby/1.9.1/gems/squash_ruby-1.0.1/lib/squash/ruby.rb:360:in `exception_info_hash'
        from /app/vendor/bundle/ruby/1.9.1/gems/squash_rails-1.0.0/lib/squash/rails.rb:34:in `exception_info_hash_with_rails'
        from (irb):28
        from /app/vendor/bundle/ruby/1.9.1/gems/railties-3.2.11/lib/rails/commands/console.rb:47:in `start'
        from /app/vendor/bundle/ruby/1.9.1/gems/railties-3.2.11/lib/rails/commands/console.rb:8:in `start'
        from /app/vendor/bundle/ruby/1.9.1/gems/railties-3.2.11/lib/rails/commands.rb:41:in `<top (required)>'
        from script/rails:6:in `require'
        from script/rails:6:in `<main>'

I'm not sure why this isn't posting to $stderr because it would have made my debugging a lot simpler if that error had just come up immediately (furthermore, squash_rails should really be outputting these to the Rails.logger so it's more obvious something has failed when tailing logs).

It seems that when I deploy to heroku the application directory is no longer a git directory so it can't automatically retrieve revision data -- you may want to note something along these lines in the documentation. I don't want to have to manually update that revision version everytime I commit though so I'll probably find some way to get that value during the heroku deploy process and set it in the app (most likely via a buildpack I've already started editing to handle private ssh keys on heroku so it can grab private repos).

I guess the actionable item I'm asking about on this pull request would be to make that 'failsafe' logging use the Rails logger, and not log to some obscure "log/abc.xyz" file.

cap deploy
cap aborted!
undefined method `instance' for Capistrano::Configuration:Class
config/deploy.rb:1:in `<top (required)>'
/Users/paule/.rbenv/versions/2.0.0/bin/cap:23:in `load'
/Users/paule/.rbenv/versions/2.0.0/bin/cap:23:in `<main>'
Tasks: TOP => production
(See full trace by running task with --trace)

Is the library supposed to work with Capistrano 3? Is there some known workaround?