rollbar

README

rollbar

rollbar is a Go Rollbar client that makes it easy to report errors to Rollbar with stacktraces. Errors are sent to Rollbar asynchronously in a background goroutine.

Because Go's error type doesn't include stack information from when it was set or allocated, rollbar uses the stack information from where the error was reported.

You may also want to look at:

• stvp/roll - Simpler, synchronous (no background goroutine) with a nicer API.

Installation

Standard installation to your GOPATH via go get:

go get github.com/stvp/rollbar

Documentation

API docs on godoc.org

Usage

package main

import (
  "github.com/stvp/rollbar"
)

func main() {
  rollbar.Token = "MY_TOKEN"
  rollbar.Environment = "production" // defaults to "development"

  result, err := DoSomething()
  if err != nil {
    // Error reporting
    rollbar.Error(rollbar.ERR, err)
  }

  // Message reporting
  rollbar.Message("info", "Message body goes here")

  // Block until all queued messages are sent to Rollbar.
  // You can do this in a defer() if needed.
  rollbar.Wait()
}

Running Tests

Set up a dummy project in Rollbar and pass the access token as an environment variable to go test:

TOKEN=f0df01587b8f76b2c217af34c479f9ea go test

And verify the reported errors manually in the Rollbar dashboard.

Other Resources

For best practices and more information on how to handle errors in Go, these are some great places to get started:

• Error Handling in Go
• Why does Go not have exceptions?
• Defer, Panic and Recover
• pkg/errors

Contributors

Thanks, all!

• @kjk
• @nazwa
• @ossareh
• @paulmach
• @Soulou
• @tike
• @tysonmote
• @marcelgruber
• @karlpatr
• @sumeet
• @dfuentes77
• @seriousben

Documentation

Index

• Constants
• Variables
• func Error(level string, err error, fields ...*Field)
• func ErrorWithStack(level string, err error, stack Stack, fields ...*Field)
• func ErrorWithStackSkip(level string, err error, skip int, fields ...*Field)
• func Errorf(level string, format string, args ...interface{})
• func Message(level string, msg string)
• func PostErrors() <-chan error
• func RequestError(level string, r *http.Request, err error, fields ...*Field)
• func RequestErrorWithStack(level string, r *http.Request, err error, stack Stack, fields ...*Field)
• func RequestErrorWithStackSkip(level string, r *http.Request, err error, skip int, fields ...*Field)
• func Wait()
• type ErrHTTPError
  • func (e ErrHTTPError) Error() string
• type Field
• type Frame
• type Stack
  • func BuildStack(skip int) Stack
  • func BuildStackWithCallers(callers []uintptr) Stack

Constants

const (
	// NAME is the name of this notifier library as reported to the Rollbar API.
	NAME = "go-rollbar"

	// VERSION is the version number of this notifier library as reported to the
	// Rollbar API.
	VERSION = "0.4.0"

	// CRIT is the critical Rollbar severity level as reported to the Rollbar
	// API.
	CRIT = "critical"

	// ERR is the error Rollbar severity level as reported to the Rollbar API.
	ERR = "error"

	// WARN is the warning Rollbar severity level as reported to the Rollbar API.
	WARN = "warning"

	// INFO is the info Rollbar severity level as reported to the Rollbar API.
	INFO = "info"

	// DEBUG is the debug Rollbar severity level as reported to the Rollbar API.
	DEBUG = "debug"

	// FILTERED is the text that replaces all sensitive values in items sent to
	// the Rollbar API.
	FILTERED = "[FILTERED]"
)

Variables

var (
	// Token is the Rollbar access token under which all items will be reported.
	// If Token is blank, no errors will be reported to Rollbar.
	Token = ""

	// Environment is the environment under which all items will be reported.
	Environment = "development"

	// Platform is the platform reported for all Rollbar items. The default is
	// the running operating system (darwin, freebsd, linux, etc.) but it can
	// also be application specific (client, heroku, etc.).
	Platform = runtime.GOOS

	// Endpoint is the URL destination for all Rollbar item POST requests.
	Endpoint = "https://api.rollbar.com/api/1/item/"

	// Buffer is the maximum number of errors that will be queued for sending.
	// When the buffer is full, new errors are dropped on the floor until the API
	// can catch up.
	Buffer = 1000

	// FilterFields is a regular expression that matches field names that should
	// not be sent to Rollbar. Values for these fields are replaced with
	// "[FILTERED]".
	FilterFields = regexp.MustCompile("password|secret|token")

	// ErrorWriter is the destination for errors encountered while POSTing items
	// to Rollbar. By default, this is stderr. This can be nil.
	ErrorWriter io.Writer = os.Stderr

	// CodeVersion is the optional code version reported to the Rollbar API for
	// all items.
	CodeVersion = ""
)

Functions

func Error

func Error(level string, err error, fields ...*Field)

Error asynchronously sends an error to Rollbar with the given severity level. You can pass, optionally, custom Fields to be passed on to Rollbar.

func ErrorWithStack

func ErrorWithStack(level string, err error, stack Stack, fields ...*Field)

ErrorWithStack asynchronously sends and error to Rollbar with the given stacktrace and (optionally) custom Fields to be passed on to Rollbar.

func ErrorWithStackSkip

func ErrorWithStackSkip(level string, err error, skip int, fields ...*Field)

ErrorWithStackSkip asynchronously sends an error to Rollbar with the given severity level and a given number of stack trace frames skipped. You can pass, optionally, custom Fields to be passed on to Rollbar.

func Errorf

func Errorf(level string, format string, args ...interface{})

func Message

func Message(level string, msg string)

Message asynchronously sends a message to Rollbar with the given severity level.

func PostErrors

func PostErrors() <-chan error

PostErrors returns a channel that receives all errors encountered while POSTing items to the Rollbar API.

func RequestError

func RequestError(level string, r *http.Request, err error, fields ...*Field)

RequestError asynchronously sends an error to Rollbar with the given severity level and request-specific information. You can pass, optionally, custom Fields to be passed on to Rollbar.

func RequestErrorWithStack

func RequestErrorWithStack(level string, r *http.Request, err error, stack Stack, fields ...*Field)

RequestErrorWithStack asynchronously sends an error to Rollbar with the given severity level, request-specific information provided by the given http.Request, and a custom Stack. You You can pass, optionally, custom Fields to be passed on to Rollbar.

func RequestErrorWithStackSkip

func RequestErrorWithStackSkip(level string, r *http.Request, err error, skip int, fields ...*Field)

RequestErrorWithStackSkip asynchronously sends an error to Rollbar with the given severity level and a given number of stack trace frames skipped, in addition to extra request-specific information. You can pass, optionally, custom Fields to be passed on to Rollbar.

func Wait

func Wait()

Wait will block until the queue of errors / messages is empty. This allows you to ensure that errors / messages are sent to Rollbar before exiting an application.

Types

type ErrHTTPError

type ErrHTTPError int

ErrHTTPError is an HTTP error status code as defined by http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

func (ErrHTTPError) Error

func (e ErrHTTPError) Error() string

Error implements the error interface.

type Field

type Field struct {
	Name string
	Data interface{}
}

Field is a custom data field used to report arbitrary data to the Rollbar API.

type Frame

type Frame struct {
	Filename string `json:"filename"`
	Method   string `json:"method"`
	Line     int    `json:"lineno"`
}

Frame is a single line of executed code in a Stack.

type Stack

type Stack []Frame

Stack represents a stacktrace as a slice of Frames.

func BuildStack

func BuildStack(skip int) Stack

BuildStack builds a full stacktrace for the current execution location.

func BuildStackWithCallers

func BuildStackWithCallers(callers []uintptr) Stack

BuildStackWithCallers builds a full stackstrace from the given list of callees.