Rails Notifier For Yeller

This is the Rails client library for http://yellerapp.com. It lets you automatically detect errors in your application, and reports them via Yeller's API, so you can debug and fix them quickly.

Installation

yeller_ruby is distributed via rubygems. If you use bundler, add it to your Gemfile:

gem "yeller_ruby"

Otherwise you can install it:

gem install yeller_ruby

Rails

The Rails plugin relies on the same global instance of the client that the rack one does, only it configures it in a slightly different way:

require 'yeller/rails'
Yeller::Rails.configure do |config|
  config.token = 'YOUR API KEY HERE'
end

This also sets up the error logger for yeller as the Rails logger (see above for more about error loggers), and hooks into Rails via a railtie so that exceptions are caught correctly. Once you've done Yeller::Rails.configure, everything else should be automatic.

Once you've initialized the gem, you can check if everything works using the rake task (this is for rails apps only):

bundle exec rake yeller:verify

That will tell you if your setup is sending errors to rails.

Sending Custom Data Via Rails Controllers

Yeller tracks any data that might be helpful from a request as arbitrary JSON. To hook into that from Rails, you can define a yeller_custom_data method in your ApplicationController, that returns a hash of any data you want to send up to Yeller:

class ApplicationController < ActionController::Base
  def yeller_custom_data
    if current_team
      {:team => current_team.to_h}
    end
  end
end

Yeller::Rails already includes the params and session from the HTTP request in this payload.

Sending Affected Users

Yeller supports tracking the users affected by a particular exception. If you already have a #current_user method defined on the controller an exception comes from, and it has an #id that is an integer, then Yeller::Rails will automatically include it. If not, feel free to override #yeller_user_data to return a user with the right id:

class ApplicationController < ActionController::Base
  def yeller_user_data
    if logged_in_user
      {"user" : {"id" => logged_in_user.id }}
    end
  end
end

Reporting Other Errors

Yeller::Rails lets you send errors outside of Rails as well:

Yeller::Rails.report(my_exception)

You can send additional information along with the exception to aid in debugging:

Yeller::Rails.report(my_exception,
  # the url the user was hitting when this error happened
  :url => self.job.url,
  # the controller/background job/handler/etc
  :location => MyJobClass,
  # a hash of any data you want to include
  :custom_data => {:params => self.job_params}
)

Additional Configuration Options

The Rails client supports a few configuration options outside of the api token. You can change which servers you report to, override the hostname that's reported, or override the environment:

Yeller::Rails.configure do |config|
  config.token = 'YOUR_TOKEN_HERE'
  config.environment = 'production'
  config.host = 'myserver.example.com'

  # to remove the default set of yeller api servers:
  config.remove_default_servers

  # to add a custom https server:
  config.add_server 'example.com', 443

  # to add a custom insecure http server (not recommended,
  # and yellerapp.com's servers don't support http, for
  # security reasons. Mostly just used for testing.
  config.add_insecure_server 'example.com', 80

  # to add a 'development environment'
  # exceptions aren't reported in development environments
  config.development_environments << 'staging'

  # to override the default development environments
  config.development_environments = ['test']
end

Robustness

This client does smart roundtripping/timeouts, so it can handle problems with individual yeller servers. After trying all the servers twice, it will stop reporting the current exception, then try each one again for the next one.

Note that in the case of network partitions, this can lead to an exception being recorded multiple times, e.g. if a connection fails (leading to a socket error) whilst reading the response from the api, but after the api has received the error. We err on the side of double reporting errors rather than potentially missing them.

What happens if the Yeller api throws an error?

If the yeller api fails after trying each server twice, the client will report this error to it's error handler, which by default logs to stdout.

You can change this behaviour in the configuration:

yeller_client = Yeller.client do |client|
  client.token = 'YOUR_TOKEN_HERE'
  client.environment = 'production'
  client.host = 'myserver.example.com'
  client.error_handler = YOUR_ERROR_HANDLER
end

error_handler is any object that responds to handle, a method that takes the http api error as it's sole argument. Yeller also ships with a logging error handler, so if you have a logger in your application already, you can use that:

config.error_handler = Yeller::LogErrorHandler.new(your_logger)

Marking In App Stacktrace Frames

Yeller can highlight stacktrace lines coming from your application, and hide those that don't. This can make a big difference when reading what would otherwise be very long Ruby stacktraces:

Overriding the default project root

By default, Yeller uses Rails.root for the project root, falling back to Dir.pwd. If neither of those are correct, you can override it in the configuration block:

Yeller::Rails.configure do |client|
  client.token = "YOUR_TOKEN_HERE"
  # other configuration here
  client.project_root = "/my_special_project_root"
end

Note that this doesn't affect which frames you can see - you can always display all the frames:

Questions

If you have any questions, feel free to shoot me an email, .

Bugs? Improvements? This Client Library is Open Source

If you're curious about this library, it's open source, and available on: github

Clients