Raygun.io

Last Updated: 04 June 2014

Raygun.io is an add-on that makes finding, diagnosing and fixing errors in your software fast and easy.

Get deep insight, stack traces, environment information, intelligent notifications, trend analysis and much more. Never be in the dark about software problems again.

Raygun.io is accessible via an API and has supported client libraries for Java, Ruby, Python, Node.js, JavaScript, .Net, ColdFusion and PHP.

Provisioning the add-on

Raygun.io can be attached to a Heroku application via the CLI:

$ heroku addons:add raygun
-----> Adding raygun to sharp-mountain-4005... done, v18 (free)

Once Raygun.io has been added a RAYGUN_APIKEY setting will be available in the app configuration and will contain the API key that can be used to submit errors to the Raygun API. This can be confirmed using the heroku config:get command.

$ heroku config:get RAYGUN_APIKEY
http://user:pass@instance.ip/resourceid

After installing Raygun.io the application should be configured to fully integrate with the add-on.

Using with Rails 3.x - 4.x

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Raygun.io client library.

gem 'raygun4ruby'

Update application dependencies with bundler.

$ bundle install

Use the generator to setup the provider.

$ rails g raygun:install your_api_key

You can use the provider for manual exception tracking as well.

require 'rubygems'
require 'raygun4ruby'

begin
  # your code here
rescue Exception => e
  Raygun.track_exception(e)
end

Using with Python

The easiest way to install Raygun is using pip

$ pip install raygun4py

In general, after importing the module with:

from raygun4py import raygunprovider

You’ll want to provide a callback function to sys.excepthook. This will pick up all uncaught exceptions that your program throws. It needs three parameters: the type, value and traceback. In the function, create a new raygunprovider.RaygunSender, then call send() on that object, passing in the parameters.

import sys, logging, os
from raygun4py import raygunprovider

logger = logging.getLogger("mylogger")

rgHandler = raygunprovider.RaygunHandler("{{Place your API key here}}")

logger.addHandler(rgHandler)

def log_exception(exc_type, exc_value, exc_traceback):
    print "Logging: %s" % exc_value
    logger.error("A python error occurred", exc_info = (exc_type, exc_value, exc_traceback))

sys.excepthook = log_exception

• If you are in a web server environment and have HTTP request details available, you can pass these and the headers through in a dictionary (as in test.py).

Using with Java

These instructions assume you have a Maven project with a POM file set up in Eclipse, but this is also applicable to other IDEs and environments.

1. Open your project’s pom.xml in Eclipse. Click on Dependencies -> Add. In the pattern search box, type com.mindscapehq.
2. Add com.mindscape.raygun4java and com.mindscapehq.core, version 1.2.1. If you are working in a web environment, get the webprovider jar too. If you wish to grab the example project, you can also get the sampleapp jar.
3. Save your POM, and the dependencies should appear in Maven Dependencies.

If you are in a shell/text editor environment, you can run mvn install from the directory containing your project’s pom.xml. You will also need to add a dependency node for the webprovider package.

To catch all exceptions in your application, and to send them to Raygun, set up an Unhandled Exception handler. Then inside it create a RaygunClient and call Send() on it, passing in the exception. The way this is done will vary based on what framework you are using.

public void uncaughtException(Thread t, Throwable e) {
  RaygunClient client = new RaygunClient("YOUR_APP_API_KEY");
  client.Send(e);
}

Presented below is a naive example that just uses plain JSPs - this architecture is obviously not recommended. A similar method will work for raw servlets if happen to be using those.

Inside web.xml

<error-page>
  <exception-type>java.lang.Throwable</exception-type>
  <location>/error.jsp</location>
</error-page>

Inside error.jsp

<%@ page isErrorPage="true" %>
<%@ page import="mindscape.raygun4java.servlet.RaygunClient" %>

<%
RaygunClient client = new RaygunClient("YOUR_APP_API_KEY", request);

client.Send(exception);
%>

When an exception is thrown from another JSP, this page will take care of the sending.

Note: all Java dynamic web page projects must have core-1.2.1.jar, webprovider-1.2.1.jar and gson-2.1.jar on their build path.

Using with Node

Install the module with

$ npm install raygun

You can then use it as so

var raygun = require('raygun');
var raygunClient = new raygun.Client().init({ apiKey: 'your API key' });
raygunClient.send(theError);

// For express, at the end of the middleware definitions:
app.use(raygunClient.expressHandler);

Dashboard

Raygun is designed to make it a pleasure to track your software errors. You shouldn’t want to stab yourself in the eye just because it’s a developer and operations tool!

The Raygun dashboard paints a beautiful picture of your overall software health - how are errors trending recently? How many have you resolved? What’s the 7 day history looking like? Get this information at a glance.

Below the visuals is a list of recently seen, smartly grouped, errors. See when they last occurred, how often and choose to drill in if needed.

The dashboard can be accessed via the CLI:

$ heroku addons:open raygun
Opening raygun for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select Raygun.io from the Add-ons menu.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade raygun:newplan
-----> Upgrading raygun:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: raygun:newplan

Removing the add-on

Raygun.io can be removed via the CLI.

$ heroku addons:remove raygun
-----> Removing raygun from sharp-mountain-4005... done, v20 (free)

Support

All Raygun.io support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at the Raygun forums.

Additional Resources

• Follow @raygunio
• Like Raygun on Facebook
• +1 Raygun on Google+
• Raygun.io Blog