Airbrake - 官方Airbrake的Ruby on Rails库
Airbrake - 官方Airbrake的Ruby on Rails库(和其他基于Rack的框架)
Ruby 错误处理
共883Star
详细介绍
Airbrake
Introduction
Airbrake is an online tool that provides robust exception tracking in any of your Ruby applications. In doing so, it allows you to easily review errors, tie an error to an individual piece of code, and trace the cause back to recent changes. The Airbrake dashboard provides easy categorization, searching, and prioritization of exceptions so that when errors occur, your team can quickly determine the root cause.
Looking for the old version?
Airbrake V5 was released on 18th December 2015. Here is a guide for migrating from v4 to v5.
You can find the V4 code here.
Key features
This library is built on top of Airbrake Ruby. The difference between Airbrake and Airbrake Ruby is that the airbrake
gem is just a collection of integrations with frameworks or other libraries. The airbrake-ruby
gem is the core library that performs exception sending and other heavy lifting.
Normally, you just need to depend on this gem, select the integration you are interested in and follow the instructions for it. If you develop a pure frameworkless Ruby application or embed Ruby and don't need any of the listed integrations, you can depend on the airbrake-ruby
gem and ignore this gem entirely.
The list of integrations that are available in this gem includes:
- Heroku support (as an add-on)
- Web frameworks
- Job processing libraries
- Other libraries
- Rake[link]
- Plain Ruby scripts[link]
Paying Airbrake plans support the ability to track deployments of your application in Airbrake. We offer several ways to track your deployments:
Installation
Bundler
Add the Airbrake gem to your Gemfile:
gem 'airbrake', '~> 5.6'
Manual
Invoke the following command from your terminal:
gem install airbrake
Configuration
Rails
Airbrake v5 is already here (but we still support Airbrake v4)
If you are migrating from Airbrake v4, please read our migration guide.
Since the 5th major release of the Airbrake gem we support only Rails 3.2+ and Ruby 1.9+. Don't worry, if you use older versions of Rails or Ruby, just continue using them with Airbrake v4: we still support it. However, v4 is feature frozen. We accept only bugfixes.
In the meantime, consider upgrading to Airbrake v5, as you miss a lot of new features, such as support for multiple Airbrake configurations inside one Rails project (you can report to different Airbrake projects in the same Ruby process), nested exceptions, multiple asynchronous workers support, JRuby's Java exceptions and many more.
Integration
To integrate Airbrake with your Rails application, you need to know your project id and project key. Invoke the following command and replace PROJECT_ID
and PROJECT_KEY
with your values:
rails g airbrake PROJECT_ID PROJECT_KEY
Heroku add-on users can omit specifying the key and the id and invoke the command without arguments (Heroku add-on's environment variables will be used) (Heroku add-on docs):
rails g airbrake
This command will generate the Airbrake configuration file under config/initializers/airbrake.rb
. Make sure that this file is checked into your version control system. This is enough to start Airbraking.
In order to configure the library according to your needs, open up the file and edit it. The full list of supported configuration options is available online.
To test the integration, invoke a special Rake task that we provide:
rake airbrake:test
In case of success, a test exception should appear in your dashboard.
The notify_airbrake controller helpers
The Airbrake gem defines two helper methods available inside Rails controllers: #notify_airbrake
and #notify_airbrake_sync
. If you want to notify Airbrake from your controllers manually, it's usually a good idea to prefer them over Airbrake.notify
, because they automatically add information from the Rack environment to notices. #notify_airbrake
is asynchronous (immediately returns nil
), while #notify_airbrake_sync
is synchronous (waits for responses from the server and returns them). The list of accepted arguments is identical to Airbrake.notify
.
Additional features: user reporting, sophisticated API
The library sends all uncaught exceptions automatically, attaching the maximum possible amount information that can help you to debug errors. The Airbrake gem is capable of reporting information about the currently logged in user (id, email, username, etc.), if you use an authentication library such as Devise. The library also provides a special API for manual error reporting. The description of the API is available online.
Automatic integration with Rake tasks and Rails runner
Additionally, the Rails integration offers automatic exception reporting in any Rake tasks[link] and Rails runner.
Integration with filter_parameters
If you want to reuse Rails.application.config.filter_parameters
in Airbrake you can configure your notifier the following way:
# config/initializers/airbrake.rb
Airbrake.configure do |c|
c.blacklist_keys = Rails.application.config.filter_parameters
end
There are a few important details:
- You must load
filter_parameter_logging.rb
before the Airbrake config - If you use Lambdas to configure
filter_parameters
, you need to convert them to Procs. Otherwise you will getArgumentError
- If you use Procs to configure
filter_parameters
, the procs must return an Array of keys compatible with the Airbrake whitelist/blacklist option (String, Symbol, Regexp)
Consult the example application, which was created to show how to configure filter_parameters
.
Sinatra
To use Airbrake with Sinatra, simply require
the gem, configure it and use
our Rack middleware.
# myapp.rb
require 'sinatra/base'
require 'airbrake'
Airbrake.configure do |c|
c.project_id = 113743
c.project_key = 'fd04e13d806a90f96614ad8e529b2822'
# Display debug output.
c.logger.level = Logger::DEBUG
end
class MyApp < Sinatra::Base
use Airbrake::Rack::Middleware
get('/') { 1/0 }
end
run MyApp.run!
To run the app, add a file called config.ru
to the same directory and invoke rackup
from your console.
# config.ru
require_relative 'myapp'
That's all! Now you can send a test request to localhost:9292
and check your project's dashboard for a new error.
curl localhost:9292
If your Sinatra app consists of subprojects and you want to capture errors separately for each subproject, make sure to configure it accordingly.
Rack
To send exceptions to Airbrake from any Rack application, simply use
our Rack middleware, and configure the default notifier.
require 'airbrake'
Airbrake.configure do |c|
c.project_id = 113743
c.project_key = 'fd04e13d806a90f96614ad8e529b2822'
end
use Airbrake::Rack::Middleware
Note: be aware that by default the library doesn't filter any parameters, including user passwords. To filter out passwords add a filter.
Appending information from Rack requests
If you want to append additional information from web requests (such as HTTP headers), define a special hook:
Airbrake.add_rack_builder do |notice, request|
notice[:params][:remoteIp] = request.env['REMOTE_IP']
end
request
here is a normal Rack request.
Configuring individual notifier for each subproject
If your app consists of multiple components and you want to log errors from each component to its own Airbrake project, you can pass second argument to our Rack middleware. First, make sure to configure a named notifier. Next, pass the name to the middleware:
require 'airbrake'
# 1 - Configure a notifier for :app2.
Airbrake.configure(:app2) do |c|
c.project_id = 113743
c.project_key = 'fd04e13d806a90f96614ad8e529b2822'
end
# 2 - Let Airbrake Rack middleware use the :app2 notifier to send errors.
use Airbrake::Rack::Middleware, :app2
Sidekiq
We support Sidekiq v2, v3 and v4. The configurations steps for them are identical. Simply require
our error handler and you're done:
require 'airbrake/sidekiq/error_handler'
If you required Sidekiq before Airbrake, then you don't even have to require
anything manually and it should just work out-of-box.
ActiveJob
No additional configuration is needed. Simply ensure that you have configured your Airbrake notifier.
If you see duplicate error entries in your dashboard, you can avoid them by ignoring the ActiveJob wrapper. Just add a filter like this one:
Airbrake.add_filter do |notice|
if notice[:context][:action] == 'ActiveJob::QueueAdapters::DelayedJobAdapter::JobWrapper'
notice.ignore!
end
end
Resque
Since Airbrake v5 the gem provides its own failure backend. The old way of integrating Resque doesn't work. If you upgrade to Airbrake v5, just make sure that you require airbrake/resque/failure
instead of resque/failure/airbrake
. The rest remains the same.
Integrating with Rails applications
If you're working with Resque in the context of a Rails application, create a new initializer in config/initializers/resque.rb
with the following content:
# config/initializers/resque.rb
require 'airbrake/resque/failure'
Resque::Failure.backend = Resque::Failure::Airbrake
That's all configuration.
General integration
Any Ruby app using Resque can be integrated with Airbrake. If you can require the Airbrake gem after Resque, then there's no need to require airbrake/resque/failure
anymore:
require 'resque'
require 'airbrake'
Resque::Failure.backend = Resque::Failure::Airbrake
If you're unsure, just configure it similar to the Rails approach. If you use multiple backends, then continue reading the needed configuration steps in the Resque wiki (it's fairly straightforward).
DelayedJob
Simply require
our plugin and you're done:
require 'airbrake/delayed_job/plugin'
If you required DelayedJob before Airbrake, then you don't even have to require
anything manually and it should just work out-of-box.
Rake
Airbrake offers Rake tasks integration, which is used by our Rails integration[link]. To integrate Airbrake in any project, just require
the gem in your Rakefile
, if it hasn't been required and configure the default notifier.
# Rakefile
require 'airbrake'
Airbrake.configure do |c|
c.project_id = 113743
c.project_key = 'fd04e13d806a90f96614ad8e529b2822'
end
task :foo do
1/0
end
Plain Ruby scripts
Airbrake supports any type of Ruby applications including plain Ruby scripts. If you want to integrate your script with Airbrake, you don't have to use this gem. The Airbrake Ruby gem provides all the needed tooling.
Deploy tracking
Airbrake has the ability to track your deploys (available only for paid plans).
By notifying Airbrake of your application deployments, all errors are resolved when a deploy occurs, so that you'll be notified again about any errors that reoccur after a deployment. Additionally, it's possible to review the errors in Airbrake that occurred before and after a deploy.
There are several ways to integrate deployment tracking with your application, that are described below.
Capistrano
The library supports Capistrano v2 and Capistrano v3. In order to configure deploy tracking with Capistrano simply require
our integration from your Capfile:
# Capfile
require 'airbrake/capistrano/tasks'
If you use Capistrano 3, define the after :finished
hook, which executes the deploy notification task (Capistrano 2 doesn't require this step).
# config/deploy.rb
namespace :deploy do
after :finished, 'airbrake:deploy'
end
If you version your application, you can set the :app_version
variable in config/deploy.rb
, so that information will be attached to your deploy.
# config/deploy.rb
set :app_version, '1.2.3'
Rake task
A Rake task can accept several arguments shown in the table below:
Key | Required | Default | Example |
---|---|---|---|
ENVIRONMENT | No | Rails.env | production |
USERNAME | No | nil | john |
REPOSITORY | No | nil | https://github.com/airbrake/airbrake |
REVISION | No | nil | 38748467ea579e7ae64f7815452307c9d05e05c5 |
VERSION | No | nil | v2.0 |
In Rails
Simply invoke rake airbrake:deploy
and pass needed arguments:
rake airbrake:deploy USERNAME=john ENVIRONMENT=production REVISION=38748467 REPOSITORY=https://github.com/airbrake/airbrake
Anywhere
Make sure to require
the library Rake integration in your Rakefile.
# Rakefile
require 'airbrake/rake/tasks'
Then, invoke it like shown in the example for Rails.
Supported Rubies
- CRuby >= 1.9.2
- JRuby >= 1.9-mode
- Rubinius >= 2.2.10
Contact
In case you have a problem, question or a bug report, feel free to:
- file an issue
- send us an email
- tweet at us
- chat with us (visit airbrake.io and click on the round orange button in the bottom right corner)
License
The project uses the MIT License. See LICENSE.md for details.
Development & testing
In order to run the test suite, first of all, clone the repo, and install dependencies with Bundler.
git clone https://github.com/airbrake/airbrake.git
cd airbrake
bundle
Next, run unit tests.
bundle exec rake
In order to test integrations with frameworks and other libraries, install their dependencies with help of the following command:
bundle exec appraisal install
To run integration tests for a specific framework, use the appraisal
command.
bundle exec appraisal rails-4.2 rake spec:integration:rails
bundle exec appraisal sinatra rake spec:integration:sinatra
Pro tip: circle.yml
has the list of all integration tests and commands to invoke them.
-
36 Star
-
0 Star
-
177 Star
-
4744 Star
-
0 Star
-
5986 Star