jkraemer / redmine_airbrake

Turns Redmine into an Airbrake (http://airbrake.io/) (formerly known as Hoptoad) compatible server

Redmine Airbrake Plugin

This plugin makes Redmine act like an Airbrake server. Any exceptions caught and sent by Airbrake client libraries will create or update an issue in Redmine.

This is a complete rewrite of the redmine_hoptoad_server plugin. It supports the Airbrake XML (v2) and JSON (v3) APIs. If you need to support the ancient Hoptoad / Airbrake v1 API, use the redmine_hoptoad_server plugin instead.

Supports Redmine from 2.6 onwards.

Plugin setup

Just install the Plugin following the general Redmine plugin installation instructions at http://www.redmine.org/wiki/redmine/Plugins.

Then, go to Administration -> Settings -> Incoming emails in your Redmine and generate an API key.

Client configuration

In order to work properly, the plugin needs some data supplied by the client. This data is supplied as a hash with the following keys:

project : Redmine project identifier where issues should be created

tracker : tracker to use

api_key : Redmine API key as created above

category : Issue category (optional)

assigned_to : Redmine login of a user the tickets should get assigned to by default (optional)

author : Redmine login if the user to serve as issue creator

priority : Id of a Redmine issue priority (optional)

environment : gets prepended to the issue's subject and is stored as a custom issue field. useful to distinguish errors on a test system from those on the production system (optional)

repository_root : this optional argument overrides the project wide repository root setting (see below).

Set up the Airbrake client according to the docs found at http://airbrake.io. When it comes to configuring the client, deviate from the instructions and supply the necessary configuration like this:

Airbrake v3 (JSON API)

This will work with any current Airbrake client, i.e. the airbrake-ruby client library from version 5 onwards.

Set up a filter that adds the config hash to the Airbrake notification before it gets sent:

Airbrake.configure do |config|
  config.project_id = 1234
  config.project_key = 'secret'
  config.host = 'https://my_redmine_host.com/'
  config.root_directory = Rails.root.to_s
end

Airbrake.add_filter do |notice|
  notice[:context][:redmine_config] = {
    tracker: 'Bug',
    api_key: 'my_redmine_api_key',
    project: 'project_identifier',
    # ... other redmine_airbrake configuration options as above
  }
end

Set the project_id to any number, it is ignored by this plugin but validated by the Airbrake client. The same is true for the project_key string.

The root_directory Airbrake option shortens backtrace lines by replacing your projects installation directory with [PROJECT_ROOT] or (since airbrake-ruby 2.9+ with /PROJECT_ROOT/)

Congratulations. You can now start receiving exceptions in Redmine!

Deprecated: Transmit config via project-key

This does not work with recent (as of January 2018) versions of the airbrake client library. Since the filter-based method above that was intruced because of that should work in all cases, this is left in here mainly for historical reasons:

Airbrake.configure do |config|
  config.project_id = 1234
  config.project_key = CGI.escape({
    tracker: 'Bug',
    api_key: 'my_redmine_api_key',
    project: 'project_identifier',
    # ... other redmine_airbrake configuration options as above
  }.to_json)
  config.host = 'https://my_redmine_host.com/'
  config.root_directory = Rails.root.to_s
end

Deprecated: Airbrake v2 (XML API)

Since the Airbrake client is not designed to handle arbitrary parameters, we trick it by setting the API-Key value to a JSON-encoded hash holding our configuration. This hash may hold the following keys:

This applies e.g. to the Ruby airbrake gem in versions < 5.0:

Airbrake.configure do |config|
  config.api_key = {
    :project => 'project_identifier',
    :tracker => 'Bug',
    :api_key => 'my_redmine_api_key',
    :category => 'Development',
    :assigned_to => 'admin',
    :priority => 5,
    :environment => 'staging',
    :repository_root => '/some/path'
  }.to_json
  config.host = 'my_redmine_host.com' # the hostname your Redmine runs at
  config.port = 443                   # the port your Redmine runs at
  config.secure = true                # sends data to your server via SSL (optional.)
end

I will certainly drop support for this API at some point, please upgrade your client.

More Configuration (please read on!)

After you received the first exception in a Redmine project, you will notice two new project custom fields here. Those are Backtrace filter and Repository root.

Backtrace filter

If you'd like to (and we really recommend you do!) filter the backtraces that are shown in the journal entries created by this plugin, you can set this field to a list of expressions (one per line) to be filtered out to that field. The filtered backtrace will only contain frames from locations not matching any of these expressions.

I usually simply set my filter to [GEM_ROOT] so the filtered backtrace only contains frames in code that's not part of any Ruby gems, but if you find other code cluttering up your backtraces, you might want to include those source files as well.

Repository root

All Issues created will have a source link in their description which -- provided that you have your source repository linked to your Redmine project -- leads you directly to the file and line in your code that has caused the exception. Your repository structure most likely won't match the structure of your deployed code, so you can add an additional repository root. Just use "trunk" for a general SVN setup for instance.

You may use the :repository_root option in your application's airbrake.rb to override this setting with a custom value. This is helful in case you have multiple applications in the same repository reporting errors to the same Redmine project.

Turn off performance reporting

According to #5, the Airbrake client from 4.5 onwards has more reporting features which lead to requests this plugin cannot handle. You can turn this off in your Airbrake config:

Airbrake.configure do |config|
  # ...
  config.performance_stats = false
  config.query_stats = false
end

Dependencies

Nokogiri For parsing V2 XML requests.

airbrake-ruby for tests.

License

GPL v2 or any later version

Authors

Jens Kraemer (https://jkraemer.net)

The original redmine_hoptoad_server plugin was created by Jan Schulz-Hofen, Planio GmbH (http://plan.io).

redmine_airbrake's Issues

error class but no line in issue title when using with airbrake-ruby 2.9+

Since airbrake-ruby 2.9 this gem only writes the error class in title of the issue. So there is

RuntimeError

instead of

RuntimeError in app/controllers/application_controller.rb:12

This is because the backtrace of airbrake-ruby does not contain [PROJECT_ROOT]/some/path:12 but /PROJECT_ROOT/some/path:12. See airbrake/airbrake-ruby@d6e3855 for details.

v3 is broken after key is not given anymore in params

We have trouble using the newest airbrake-ruby gem cause the project_key is not send anymore as key param to the airbrake server.
See this commit: airbrake/airbrake-ruby@5d258a2

So the redmine_airbrake throws a 500 in the controller, cause there is no param key here:

redmine_airbrake/app/controllers/airbrake_notices_controller.rb

Line 43 in 6febdad

config = JSON.parse params[:key]

It seems the project_key is not made for transmitting all the information the redmine_airbrake plugin needs.

We monkey patched our airbrake client to make it work, but it is really ugly.

  module Patches
    module Airbrake
      module Config
         def endpoint
           @endpoint ||=
             begin
               redmine_params =
                 CGI.escape({
                   tracker: 'Exception',
                   api_key: 'foo',
                   project: 'bar',
                   assigned_to: 'developer'
                 }.to_json)
               super + "?key=#{redmine_params}"
             end
         end
      end
    end
  end

  Airbrake::Config.prepend(::Patches::Airbrake::Config)

One solution could be to implement a new config option in airbrake-ruby to give custom parameters to the url. Another option would be to post these informations as json in the request body with all other informations and patch the controller to read it from there.
What would you think?

Greetings from DD! ;)

suggest disabling of airbrake performance monitoring

Hi,

airbrake-ruby has a new performance monitoring feature since version 4.5.0, which is enabled by default. (see their changelog: https://github.com/airbrake/airbrake-ruby/blob/master/CHANGELOG.md )
This causes trouble with the redmine_airbrake plugin, cause it can not handle these requests and throws tons of exceptions. (both in the app and in the redmine log).

The feature can be simply disabled by setting:

Airbrake.configure do |config|
  # ...
  config.performance_stats = false
  config.query_stats = false
end

Maybe it would be helpfull for others if you suggest these options in your README.
I don't think we could really use these performance monitoring things to generate issues in redmine or something or do you have an idea?

Thanks and Greets!

Airbrake v3 config doesn't work

Hi,

I've upgraded airbrake to version 5.4.0.
Your example how to set configuration doesn't work, because project_key as json is not a valid URI.

I fixed it this way (added URI.encode):

Airbrake.configure do |config|
  config.project_id = 1234
  config.project_key = URI.encode({
    tracker: 'Bug',
    api_key: 'my_redmine_api_key',
    project: 'project_identifier',
    # ... other redmine_airbrake configuration options as above
  }.to_json)
  config.host = 'https://my_redmine_host.com/'
  config.root_directory = Rails.root.to_s
end