PartyFoul
Rails exceptions automatically opened as issues on GitHub
Looking for help?
If it is a bug please open an issue on GitHub.
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, a 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 occurrence 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 occurrence 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.api_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'
# Additional labels to add to issues created
# config.additional_labels = ['production']
# or
# config.additional_labels = Proc.new do |exception, env|
# []
# end
# Limit the number of comments per issue
# config.comment_limit = 10
# Setting your title prefix can help with
# distinguising the issue between environments
# config.title_prefix = Rails.env
end
You can create an OAuth token or generate an OAuth token via the OAuth Authorizations API with cURL:
curl -u <github_login> -i -d "{ \"scopes\": [\"repo\"], \"note\":[\"Test\"] }" \
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
Limiting Comments
You can specify a limit on the number of comments added to each issue. The main issue will still be updated with a count and time for each occurrence, regardless of the limit.
PartyFoul.configure do |config|
config.comment_limit = 10
end
Tracking errors outside of an HTTP request
You may want to track errors outside of a regular 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 => error
PartyFoul::RacklessExceptionHandler.handle(error, class: class_name, method: method_name, params: message)
raise error
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 notifier server.
File: config/initializers/partyfoul_sidekiq.rb
module PartyFoul
class Sidekiq
def call(worker, msg, queue)
begin
yield
rescue => error
PartyFoul::RacklessExceptionHandler.handle(error, {class: worker.class.name, method: queue, params: msg})
raise error
end
end
end
end
::Sidekiq.configure_server do |config|
config.server_middleware do |chain|
chain.add ::PartyFoul::Sidekiq
end
end
This will pass the worker class name and queue as well as all worker-related parameters off to PartyFoul before passing on the exception.
Authors
We are very thankful for the many contributors
Versioning
This gem follows Semantic Versioning
Want to help?
Please do! We are always looking to improve this gem. Please see our Contribution Guidelines on how to properly submit issues and pull requests.
Legal
DockYard, LLC Β© 2013