PartyFoul

Rails exceptions automatically opened as issues on Github

Looking for help?

If it is a bug please open an issue on Github. If you need help using the gem please ask the question on Stack Overflow. Be sure to tag the question with DockYard so we can find it.

About

PartyFoul captures exceptions in your application and does the following:

Attempt to find a matching issue in your Github repo
If no matching issue is found an new issue is created with a unique title, session information, and stack trace. The issue is tagged as a bug. A new comment is added with relevant data on the application state.
If an open issue is found the occurence count and time stamp is updated. A new comment is added with relevant data on the application state.
If a closed issue is found the occurence count and time stamp is updated. The issue is reopened and a regression tag is added. A new comment is added with relevant data on the application state.
If the issue is marked as wontfix the issue is not updated nor is a new issue created. No comments are added.

Installation

Note We highly recommend that you create a new Github account that is a collaborator on your repository. Use this new account's credentials for the installation below. If you use your own account you will not receive emails when issues are created, updated, reopened, etc... because all of the work is done as your account.

In your Gemfile add the following:

gem 'party_foul'

Rails

If you are using Rails you can run the install generator.

rails g party_foul:install

This prompts you for the Github credentials of the account that is opening the issues. The OAuth token for that account is stored in config/initializers/party_foul.rb. You may want to remove the token string and store in an environment variable. It is best not to store the token in version control.

Add as the very last middleware in your production Rack stack in config/environments/production.rb

config.middleware.use('PartyFoul::Middleware')

Other

You need to initialize PartyFoul, use the following:

PartyFoul.configure do |config|
  # The collection of exceptions PartyFoul should not be allowed to handle
  # The constants here *must* be represented as strings
  config.blacklisted_exceptions = ['ActiveRecord::RecordNotFound', 'ActionController::RoutingError']

  # The OAuth token for the account that is opening the issues on Github
  config.oauth_token            = 'abcdefgh1234567890'

  # The API endpoint for Github. Unless you are hosting a private
  # instance of Enterprise Github you do not need to include this
  config.endpoint               = 'https://api.github.com'

  # The Web URL for Github. Unless you are hosting a private
  # instance of Enterprise Github you do not need to include this
  config.web_url                = 'https://github.com'

  # The organization or user that owns the target repository
  config.owner                  = 'owner_name'

  # The repository for this application
  config.repo                   = 'repo_name'

  # The branch for your deployed code
  # config.branch               = 'master'
end

You can generate an OAuth token from via the OAuth Authorizations API with cURL:

curl -u <github_login> -i -d "{ \"scopes\": [\"repo\"] }" \
https://api.github.com/authorizations

Customization

Labels

You can specify an additional array of labels that will be applied to the issues PartyFoul creates.

PartyFoul.configure do |config|
  config.additional_labels = ['front-end']
end

You can also provide a Proc that is passed the exception and the environment.

PartyFoul.configure do |config|
  config.additional_labels = Proc.new do |exception, env|
    labels = if env["HTTP_HOST"] =~ /beta\./
      ['beta']
    else
      ['production']
    end
    if exception.message =~ /PG::Error/
      labels << 'database'
    end
    labels
  end
end

Background Processing

You can specify the adapter with which the exceptions should be handled. By default, PartyFoul includes the PartyFoul::Processors::Sync which handles the exception synchronously. To use your own adapter, include the following in your PartyFoul.configure block:

PartyFoul.configure do |config|
  config.processor = PartyFoul::Processors::MyBackgroundProcessor
end

class PartyFoul::Processors::MyBackgroundProcessor
  def self.handle(exception, env)
    # Enqueue the exception, then in your worker, call
    # PartyFoul::ExceptionHandler.new(exception, env).run
  end
end

PartyFoul comes with the following background processing adapters:

These adapters are not loaded by default. You must explicitly require if you want to use:

require 'party_foul/processors/sidekiq'

PartyFoul.configure do |config|
  config.processor = PartyFoul::Processors::Sidekiq
end

Tracking errors outside of an HTTP request

You may want to track errors outside of a reqular HTTP stack. In that case you will need to make sure of the PartyFoul::RacklessExceptionHandler.

The code that you want to handle should be wrapped like so:

begin
  ... # some code that might raise an error
rescue => e
  PartyFoul::RacklessExceptionHandler.handle(e, {class: class_name, method: method_name, params: message)
  raise e
end

Tracking errors in a Sidekiq worker

In order to use PartyFoul for exception handling with Sidekiq you will need to create an initializer with some middleware configuration. The following example is based on using Sidekiq with another exception notifiier server.

File: config/initializers/partyfoul_sidekiq.rb

module PartyFoul
  class Sidekiq
    def call(worker, msg, queue)
      begin
        yield
      rescue => ex
        PartyFoul::RacklessExceptionHandler.handle(ex, {class: worker.class.name, method: queue, params: msg})
        raise
      end
    end
  end
end

::Sidekiq.configure_server do |config|
  config.server_middleware do |chain|
    chain.add ::PartyFoul::Sidekiq
  end
end