honeybadger

README

Honeybadger Go Client

This is an unofficial notifier library for integrating Go applications with Honeybadger.

Usage

Getting Started

First you'll need to import the library and set your Honeybadger API key and an environment name for your application:

import "github.com/jcoene/honeybadger"

func main() {
  // Set the API key
  honeybadger.ApiKey = "abcdef"

  // Set the application environment
  honeybadger.Environment = "production"
}

Later (probably when recovering from some kind of panic or error), you can create and send an error report:

func DoStuff() (err error) {
  if err = doOtherThing(); err != nil {
    // Create a new report with 0 call stack inflation (more on that later)
    // Give it the error we received as the message (could be anything)
    report, err2 := honeybadger.NewReport(err)

    // Send the error (asynchronously in a Goroutine)
    report.Dispatch()
  }
}

Adding Context

It's possible (I'd say advisable) to add some context for the failure:

// Create the report
report, _ := honeybadger.NewReport(err)

// Set the request URL
report.Request.URL = myHttpReq.URL

// Set all of the incoming request headers. Could be anything.
for k, v := range myHttpReq.Header {
  report.AddContext(k, v[0])
}

The Report object you create by calling NewReport is self describing and can be manipulated as you see fit. Inspect it and make it work for you.

There are a few additional convenience methods for adding context of various types. AddContext, AddParam, and AddSession all take a key and value to build on the hash for their respective category.

Labels and Backtraces

Your error reports are automatically labeled and given backtraces based on the call stack. This is accomplished using the Go runtime package. The automatically generated labels will only be accurate if the library can properly determine the origin of the error.

If you do not call honeybadger.NewReport directly from the source of the error then you will need to specify the number of intermediate calls so that the library can properly identify the original caller. You can do this by creating your error report with NewReportWithSkipCallers instead of NewReport.

For example, let's say you want to have a helper function in your service to report errors, it should call NewReportWithSkipCallers with a depth of 1:

  func Get(req, resp, ...) {
    if err = doOtherThing; err != nil {
      // Oh no, let ops know that things aren't going so well!
      reportError(req, resp, err)
    }
  }

  // ...

  func reportError(req, resp, err) {
    // Create the report with an inflated stack depth of 1
    report, err2 := honeybadger.NewReportWithSkipCallers(err, 1)

    // Fill in a bunch of useful information from the request
    report.Request.URL = req.URL

    // ...

    // Send
    report.Dispatch()
  }

Sending Error Reports

Use the Dispatch method to send a report asynchronously.

If you'd like to see the result of the send operation, you can call Send (which returns an error or nil).

License

MIT License.

Documentation

Index

• Variables
• func Dispatch(err error) error
• func DispatchWithContext(err error, context map[string]interface{}) error
• func Send(err error) error
• func Start(apiKey, environment string)
• type BacktraceLine
• type Error
• type Notifier
• type Report
  • func NewReport(msg interface{}) (r *Report, err error)
  • func NewReportWithSkipCallers(msg interface{}, skipCallers int) (r *Report, err error)
  • func (r *Report) AddContext(k string, v interface{})
  • func (r *Report) AddParam(k string, v interface{})
  • func (r *Report) AddSession(k string, v interface{})
  • func (r *Report) Dispatch()
  • func (r *Report) Send() (err error)
• type Request
• type Server

Variables

var (
	ApiKey      string
	Environment string
	Client      *http.Client = http.DefaultClient
)

Functions

func Dispatch

func Dispatch(err error) error

Dispatch sends a report to HB asynchronously and returns the error

func DispatchWithContext

func DispatchWithContext(err error, context map[string]interface{}) error

DispatchWithContext sends a report to HB asynchronously with context and returns the error

func Send

func Send(err error) error

Send sends a report to HB synchronously and returns the error

func Start

func Start(apiKey, environment string)

Types

type BacktraceLine

type BacktraceLine struct {
	Method string `json:"method"`
	File   string `json:"file"`
	Number string `json:"number"`
}

type Error

type Error struct {
	Class     string                 `json:"class"`
	Message   string                 `json:"message"`
	Backtrace []*BacktraceLine       `json:"backtrace"`
	Source    map[string]interface{} `json:"source"`
}

type Notifier

type Notifier struct {
	Name     string `json:"name"`
	Url      string `json:"url"`
	Version  string `json:"version"`
	Language string `json:"language"`
}

type Report

type Report struct {
	Notifier *Notifier `json:"notifier"`
	Error    *Error    `json:"error"`
	Request  *Request  `json:"request"`
	Server   *Server   `json:"server"`
}

func NewReport

func NewReport(msg interface{}) (r *Report, err error)

Create a new report using the given error message and current call stack.

func NewReportWithSkipCallers

func NewReportWithSkipCallers(msg interface{}, skipCallers int) (r *Report, err error)

Create a new report using the given error message and current call stack. Supply an integer indicating how many callers to skip (0 is none).

func (*Report) AddContext

func (r *Report) AddContext(k string, v interface{})

Add a key and given value to the report as context

func (*Report) AddParam

func (r *Report) AddParam(k string, v interface{})

Add a key and given value to the report as parameters

func (*Report) AddSession

func (r *Report) AddSession(k string, v interface{})

Add a key and given value to the report as session

func (*Report) Dispatch

func (r *Report) Dispatch()

Send the report asynchronously

func (*Report) Send

func (r *Report) Send() (err error)

Send the report and return an error if present

type Request

type Request struct {
	Url       string                 `json:"url"`
	Component string                 `json:"component"`
	Action    string                 `json:"action"`
	Params    map[string]interface{} `json:"params"`
	Session   map[string]interface{} `json:"session"`
	CgiData   map[string]interface{} `json:"cgi_data"`
	Context   map[string]interface{} `json:"context"`
}

type Server

type Server struct {
	ProjectRoot     map[string]interface{} `json:"project_root"`
	EnvironmentName string                 `json:"environment_name"`
	Hostname        string                 `json:"hostname"`
}