Raygun4Go adds Raygun-based error handling to your Golang code. It catches all occuring errors, extracts as much information as possible and sends the error to Raygun where it is viewable in the Crash Reporting dashboard.

Installation

Step 1 - Download the raygun4go library

$ go get github.com/MindscapeHQ/raygun4go

Step 2 - Initialize the raygun4go library

In your project, open the most global file.

• For web servers, this will probably be the file with your request handling method
• For all other programs it should be the file with the main method

To that file, add the library import statement:

import "github.com/MindscapeHQ/raygun4go"

Then add the following code at the earliest possible place in the request handling method (web servers) or the main method (everything else):

raygun, err := raygun4go.New("appName", "paste_your_api_key_here")
if err != nil {
  log.Println("Unable to create Raygun client:", err.Error())
}
defer raygun.HandleError()

If your program runs into a panic, the error will be sent to Raygun. To have this logged instead you can add the following line before the defer statement:

raygun.Silent(true)

Step 3 - Test your Raygun integration

Deploy Raygun into your production environment for best results, or raise a test exception.

Manually sending errors

Raygun4Go provides three ways that you can manually send errors to Raygun as described below.

CreateError

This is useful when you don't have an actual error object to send, but want to report that something has gone wrong. The given string will be used as the error message, and the stack trace will be the current program execution trace.

if err := raygun.CreateError("something bad happened"); err != nil {
    log.Printf("failed to report error to Raygun: %v\n", err)
}

CreateErrorWithStackTrace

This method allows you to manually send an error to Raygun with a custom message and a custom stacktrace. This can be useful when the default system stack trace is not relevant or sufficient.

To construct a StackTrace, use the AddEntry method of the StackTrace type.

st := make(raygun4go.StackTrace, 0)
st.AddEntry(42, "main", "example.go", "exampleFunc")
if err := raygun.CreateErrorWithStackTrace("something bad happened", st); err != nil {
    log.Printf("failed to report error to Raygun: %v\n", err)
}

SendError

This method sends a given error object to Raygun. If the given object is a "github.com/go-errors/errors".Error, then its stack trace will be used in the report. Otherwise the current program execution trace will be used.

err := something.Do()
if err := raygun.SendError(err); err != nil {
    log.Printf("failed to report error to Raygun: %v\n", err)
}

Options

The client returned by New has several chainable option-setting methods:

Silent(bool)

If set to true, this prevents the handler from sending the error to Raygun, printing it instead.

Request(*http.Request)

Adds the responsible http.Request to the error.

Version(string)

If your program has a version, you can add it here.

Tags([]string)

Adds the given tags to the error. These can be used for filtering later.

CustomData(interface{})

Add arbitrary custom data to you error. Will only reach Raygun if it works with json.Marshal().

User(string)

Add the name of the affected user to the error.

raygun4go.New("appName", "apiKey").User("Ronald Raygun")

Custom grouping

By default, the Raygun service will group errors together based on stacktrace content. If you have any cases where you want to control the error grouping yourself, then you can provide a custom-grouping-key callback function. Below is a simple example of this, that returns a hard-coded grouping key, which would cause all errors to be grouped together:

raygun.CustomGroupingKeyFunction(func(error, raygun4go.PostData)string{return "customKey"})

The callback takes the original error, and the Raygun PostData payload structure that is about to be serialized and sent to Raygun. In your callback, you can check these values to help build your own grouping key logic based on different cases that you want to control. For any error you don't want to group yourself, return an empty string - Raygun will then use the default grouping.