rollbar

README

rollbar

rollbar is a Golang Rollbar client that makes it easy to report errors to Rollbar with full 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, we use the stack information from where the error was reported.

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"
  rollbar.CodeVersion = "v2"                         // optional Git hash/branch/tag (required for GitHub integration)
  rollbar.ServerHost = "web.1"                       // optional override; defaults to hostname
  rollbar.ServerRoot = "github.com/heroku/myproject" // path of project (required for GitHub integration and non-project stacktrace collapsing)

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

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

  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.

Contributors

A big thank you to everyone who has contributed pull requests and bug reports:

• @kjk
• @Soulou
• @paulmach

Documentation

Index

• Constants
• Variables
• func Error(level string, err error)
• func ErrorWithExtras(level string, err error, extras map[string]interface{})
• func ErrorWithStackSkip(level string, err error, skip int)
• func ErrorWithStackSkipWithExtras(level string, err error, skip int, extras map[string]interface{})
• func Message(level string, msg string)
• func MessageWithExtras(level string, msg string, extras map[string]interface{})
• func RequestError(level string, r *http.Request, err error)
• func RequestErrorWithExtras(level string, r *http.Request, err error, extras map[string]interface{})
• func RequestErrorWithStackSkip(level string, r *http.Request, err error, skip int)
• func RequestErrorWithStackSkipWithExtras(level string, r *http.Request, err error, skip int, ...)
• func Wait()
• type CauseStacker
• type Frame
• type Stack
  • func BuildStack(skip int) Stack
  • func (s Stack) Fingerprint() string

Constants

const (
	NAME    = "heroku/rollbar"
	VERSION = "0.3.0"

	// Severity levels
	CRIT  = "critical"
	ERR   = "error"
	WARN  = "warning"
	INFO  = "info"
	DEBUG = "debug"

	FILTERED = "[FILTERED]"
)

Variables

var (
	// Rollbar access token. If this is blank, no errors will be reported to
	// Rollbar.
	Token = ""

	// All errors and messages will be submitted under this environment.
	Environment = "development"

	// API endpoint for Rollbar.
	Endpoint = "https://api.rollbar.com/api/1/item/"

	// Maximum number of errors allowed in the sending queue before we start
	// dropping new errors on the floor.
	Buffer = 1000

	// Filter HTTP Headers parameters from being sent to Rollbar.
	FilterHeaders = regexp.MustCompile("Authorization")

	// Filter GET and POST parameters from being sent to Rollbar.
	FilterFields = regexp.MustCompile("password|secret|token")

	// String describing the running code version on the server
	CodeVersion = ""

	// host: The server hostname. Will be indexed.
	ServerHost, _ = os.Hostname()

	// root: Path to the application code root, not including the final slash.
	// Used to collapse non-project code when displaying tracebacks.
	ServerRoot = ""
)

Functions

func Error

func Error(level string, err error)

Error asynchronously sends an error to Rollbar with the given severity level.

func ErrorWithExtras

func ErrorWithExtras(level string, err error, extras map[string]interface{})

Error asynchronously sends an error to Rollbar with the given severity level with extra custom data.

func ErrorWithStackSkip

func ErrorWithStackSkip(level string, err error, skip int)

ErrorWithStackSkip asynchronously sends an error to Rollbar with the given severity level and a given number of stack trace frames skipped.

func ErrorWithStackSkipWithExtras

func ErrorWithStackSkipWithExtras(level string, err error, skip int, extras map[string]interface{})

ErrorWithStackSkip asynchronously sends an error to Rollbar with the given severity level and a given number of stack trace frames skipped with extra custom data.

func Message

func Message(level string, msg string)

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

func MessageWithExtras

func MessageWithExtras(level string, msg string, extras map[string]interface{})

Message asynchronously sends a message to Rollbar with the given severity level with extra custom data. Rollbar request is asynchronous.

func RequestError

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

RequestError asynchronously sends an error to Rollbar with the given severity level and request-specific information.

func RequestErrorWithExtras

func RequestErrorWithExtras(level string, r *http.Request, err error, extras map[string]interface{})

RequestError asynchronously sends an error to Rollbar with the given severity level and request-specific information with extra custom data.

func RequestErrorWithStackSkip

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

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.

func RequestErrorWithStackSkipWithExtras

func RequestErrorWithStackSkipWithExtras(level string, r *http.Request, err error, skip int, extras map[string]interface{})

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 and extra custom data.

func Wait

func Wait()

Wait will block until the queue of errors / messages is empty.

Types

type CauseStacker

type CauseStacker interface {
	error
	Cause() error
	Stack() Stack
}

Errors can implement this interface to create a trace_chain Callers are required to call BuildStack on their own at the time the cause is wrapped.

type Frame

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

type Stack

type Stack []Frame

func BuildStack

func BuildStack(skip int) Stack

func (Stack) Fingerprint

func (s Stack) Fingerprint() string

Create a fingerprint that uniqely identify a given message. We use the full callstack, including file names. That ensure that there are no false duplicates but also means that after changing the code (adding/removing lines), the fingerprints will change. It's a trade-off.