gobrake

README

Gobrake

• Gobrake official documentation
• pkg.go.dev documentation

Introduction

Gobrake is the official notifier package for Airbrake for the Go programming language. Gobrake provides a minimalist API that enables the ability to send any Go error or panic to the Airbrake dashboard. The library is extremely lightweight, with minimal overhead.

Key features

• Simple, consistent and easy-to-use library API
• Asynchronous exception reporting
• Flexible configuration options
• Support for environments
• Add extra context to errors before reporting them
• Filters support (filter out sensitive or unwanted data that shouldn't be sent)
• Ignore errors based on class, message, status, file, or any other filter
• SSL support (all communication with Airbrake is encrypted by default)
• Notify Airbrake on panics
• Set error severity to control notification thresholds
• Support for code hunks (lines of code surrounding each backtrace frame)
• Automatic deploy tracking
• Performance monitoring features such as HTTP route statistics, SQL queries, and Job execution statistics
• Integrations with Beego, Buffalo, Echo, fasthttp, Fiber, Gin, gorilla/mux, Iris, Negroni and net/http
• Last but not least, we follow semantic versioning 2.0.0

Installation

When using Go Modules, you do not need to install anything to start using Airbrake with your Go application. Import the package and the go tool will automatically download the latest version of the package when you next build your program.

import (
	"github.com/Tixologi-Inc/gobrake"
)

With or without Go Modules, to use the latest version of the package, run:

go get github.com/Tixologi-Inc/gobrake

Installing in a new project

Create a new directory, initialize a new module and go get the library:

mkdir airbrake_example && cd airbrake_example
go mod init airbrake_example
go get github.com/Tixologi-Inc/gobrake

Example

This is the minimal example that you can use to test Gobrake with your project.

package main

import (
	"errors"

	"github.com/Tixologi-Inc/gobrake"
)

var airbrake = gobrake.NewNotifierWithOptions(&gobrake.NotifierOptions{
	ProjectId:   <YOUR PROJECT ID>, // <-- Fill in this value
	ProjectKey:  "<YOUR API KEY>", // <-- Fill in this value
	Environment: "production",
})

func main() {
	defer airbrake.Close()

	airbrake.Notify(errors.New("operation failed"), nil)
}

ProjectId & ProjectKey

You must set both ProjectId & ProjectKey.

To find your ProjectId (int64) and ProjectKey (string) navigate to your project's Settings and copy the values from the right sidebar.

Getting Started

To check the complete Guide, visit our official docs.

API

For complete API description please follow documentation on pkg.go.dev documentation.

Note: Gobrake provides middleware out of the box and you may find our example apps more helpful:

• Beego
• Buffalo
• Echo
• fasthttp
• Fiber
• Gin
• gorilla/mux
• Iris
• Negroni
• net/http

Additional notes

Exception limit

The maximum size of an exception is 64KB. Exceptions that exceed this limit will be truncated to fit the size.

Logging

We support major logging frameworks:

• There's a glog fork, which integrates with Gobrake. It provides all of original glog's functionality and adds the ability to send errors/logs to Airbrake.io.
• apex/log, to check how to integrate gobrake with apex/log, see example.
• zerolog, to check how to integrate gobrake with zerolog, see example.
• zap, to check how to integrate gobrake with zap, see example.

Supported Go versions

The library supports Go v1.17+. The CI file would be the best source of truth because it contains all Go versions that we test against.

Contact

In case you have a problem, question or a bug report, feel free to:

• file an issue
• send us an email
• tweet at us
• chat with us (visit airbrake.io and click on the round orange button in the bottom right corner)

License

The project uses the MIT License. See LICENSE.md for details.

Documentation

Index

• func GetLogger() *log.Logger
• func NewBlocklistKeysFilter(keys ...interface{}) func(*Notice) *Notice
• func SetLogger(l *log.Logger)
• type Error
• type Metric
  • func ContextMetric(c context.Context) Metric
• type Notice
  • func NewNotice(e interface{}, ctx *gin.Context, depth int) *Notice
  • func (n *Notice) SetRequest(ctx *gin.Context)
  • func (n *Notice) String() string
• type Notifier
  • func NewNotifier(projectId int64, projectKey string) *Notifier
  • func NewNotifierWithOptions(opt *NotifierOptions) *Notifier
  • func (n *Notifier) AddFilter(fn func(*Notice) *Notice)
  • func (n *Notifier) Close() error
  • func (n *Notifier) CloseTimeout(timeout time.Duration) error
  • func (n *Notifier) Flush()
  • func (n *Notifier) Notice(err interface{}, ctx *gin.Context, depth int) *Notice
  • func (n *Notifier) Notify(e interface{}, ctx *gin.Context)
  • func (n *Notifier) NotifyOnPanic()
  • func (n *Notifier) SendNotice(notice *Notice) (string, error)
  • func (n *Notifier) SendNoticeAsync(notice *Notice)
• type NotifierOptions
  • func (opt *NotifierOptions) Copy() *NotifierOptions
• type QueryInfo
• type QueueMetric
  • func ContextQueueMetric(c context.Context) *QueueMetric
  • func NewQueueMetric(c context.Context, name string) (context.Context, *QueueMetric)
  • func (t *QueueMetric) Start(c context.Context, name string) (context.Context, Span)
  • func (t *QueueMetric) WithSpan(ctx context.Context, name string, body func(context.Context) error) error
• type RemoteConfigJSON
• type RemoteSettings
• type RouteMetric
  • func ContextRouteMetric(c context.Context) *RouteMetric
  • func NewRouteMetric(c context.Context, method, route string) (context.Context, *RouteMetric)
  • func (t *RouteMetric) Start(c context.Context, name string) (context.Context, Span)
  • func (t *RouteMetric) WithSpan(ctx context.Context, name string, body func(context.Context) error) error
• type Span
  • func ContextSpan(c context.Context) Span
• type StackFrame

Examples

• NewBlocklistKeysFilter

Functions

func GetLogger

func GetLogger() *log.Logger

func NewBlocklistKeysFilter

func NewBlocklistKeysFilter(keys ...interface{}) func(*Notice) *Notice

Example

package main

import (
	"regexp"

	"github.com/Tixologi-Inc/gobrake"
)

func main() {
	notifier := gobrake.NewNotifier(1, "key")
	filter := gobrake.NewBlocklistKeysFilter("password", regexp.MustCompile("(?i)(user)"))
	notifier.AddFilter(filter)

	notice := &gobrake.Notice{
		Params: map[string]interface{}{
			"password": "slds2&LP",
			"User":     "username",
			"email":    "john@example.com",
		},
	}
	notifier.Notify(notice, nil)
}

func SetLogger

func SetLogger(l *log.Logger)

Types

type Error

type Error struct {
	Type      string       `json:"type"`
	Message   string       `json:"message"`
	Backtrace []StackFrame `json:"backtrace"`
}

type Metric

type Metric interface {
	Start(c context.Context, name string) (context.Context, Span)
}

func ContextMetric

func ContextMetric(c context.Context) Metric

type Notice

type Notice struct {
	Id    string `json:"-"` // id returned by SendNotice
	Error error  `json:"-"` // error returned by SendNotice

	Errors  []Error                `json:"errors"`
	Context map[string]interface{} `json:"context"`
	Env     map[string]interface{} `json:"environment"`
	Session map[string]interface{} `json:"session"`
	Params  map[string]interface{} `json:"params"`
}

func NewNotice

func NewNotice(e interface{}, ctx *gin.Context, depth int) *Notice

func (*Notice) SetRequest

func (n *Notice) SetRequest(ctx *gin.Context)

func (*Notice) String

func (n *Notice) String() string

type Notifier

type Notifier struct {
	Routes  *routes
	Queries *queryStats
	Queues  *queueStats
	// contains filtered or unexported fields
}

func NewNotifier

func NewNotifier(projectId int64, projectKey string) *Notifier

func NewNotifierWithOptions

func NewNotifierWithOptions(opt *NotifierOptions) *Notifier

func (*Notifier) AddFilter

func (n *Notifier) AddFilter(fn func(*Notice) *Notice)

AddFilter adds filter that can change notice or ignore it by returning nil.

func (*Notifier) Close

func (n *Notifier) Close() error

Close waits for pending requests to finish and then closes the notifier.

func (*Notifier) CloseTimeout

func (n *Notifier) CloseTimeout(timeout time.Duration) error

CloseTimeout waits for pending requests to finish with a custom input timeout and then closes the notifier.

func (*Notifier) Flush

func (n *Notifier) Flush()

Flush waits for pending requests to finish. It is recommended to be used with SendNoticeAsync().

func (*Notifier) Notice

func (n *Notifier) Notice(err interface{}, ctx *gin.Context, depth int) *Notice

Notice returns Aibrake notice created from error and request. depth determines which call frame to use when constructing backtrace.

func (*Notifier) Notify

func (n *Notifier) Notify(e interface{}, ctx *gin.Context)

Notify notifies Airbrake about the error.

func (*Notifier) NotifyOnPanic

func (n *Notifier) NotifyOnPanic()

NotifyOnPanic notifies Airbrake about the panic and should be used with defer statement.

func (*Notifier) SendNotice

func (n *Notifier) SendNotice(notice *Notice) (string, error)

SendNotice sends notice to Airbrake.

func (*Notifier) SendNoticeAsync

func (n *Notifier) SendNoticeAsync(notice *Notice)

SendNoticeAsync is like SendNotice, but sends notice asynchronously. Pending notices can be flushed with Flush().

type NotifierOptions

type NotifierOptions struct {
	// Airbrake project id.
	ProjectId int64

	// Airbrake project key.
	ProjectKey string

	// Airbrake host name. Default is https://api.airbrake.io.
	Host string

	// Airbrake host name for sending APM data.
	APMHost string

	// The host name where the remote config is located.
	RemoteConfigHost string

	// Controls the remote config feature.
	DisableRemoteConfig bool

	// Environment such as production or development.
	Environment string

	// Git revision. Default is SOURCE_VERSION on Heroku.
	Revision string

	// List of keys containing sensitive information that must be filtered out.
	// Default is password, secret.
	KeysBlocklist []interface{}

	// Disables code hunks.
	DisableCodeHunks bool

	// Controls the error reporting feature.
	DisableErrorNotifications bool

	// Controls the error reporting feature.
	DisableAPM bool

	// http.Client that is used to interact with Airbrake API.
	HTTPClient *http.Client

	// Controls the backlog reporting feature.
	// Default is false
	DisableBacklog bool
}

func (*NotifierOptions) Copy

func (opt *NotifierOptions) Copy() *NotifierOptions

Makes a shallow copy (without copying slices or nested structs; because we don't need it so far).

type QueryInfo

type QueryInfo struct {
	Method    string
	Route     string
	Query     string
	Func      string
	File      string
	Line      int
	StartTime time.Time
	EndTime   time.Time
}

type QueueMetric

type QueueMetric struct {
	Queue   string
	Errored bool
	// contains filtered or unexported fields
}

func ContextQueueMetric

func ContextQueueMetric(c context.Context) *QueueMetric

func NewQueueMetric

func NewQueueMetric(c context.Context, name string) (context.Context, *QueueMetric)

func (*QueueMetric) Start

func (t *QueueMetric) Start(c context.Context, name string) (context.Context, Span)

func (*QueueMetric) WithSpan

func (t *QueueMetric) WithSpan(ctx context.Context, name string, body func(context.Context) error) error

type RemoteConfigJSON

type RemoteConfigJSON struct {
	ProjectId   int64  `json:"project_id"`
	UpdatedAt   int64  `json:"updated_at"`
	PollSec     int64  `json:"poll_sec"`
	ConfigRoute string `json:"config_route"`

	RemoteSettings []*RemoteSettings `json:"settings"`
}

type RemoteSettings

type RemoteSettings struct {
	Name     string `json:"name"`
	Enabled  bool   `json:"enabled"`
	Endpoint string `json:"endpoint"`
}

type RouteMetric

type RouteMetric struct {
	Method      string
	Route       string
	StatusCode  int
	ContentType string
	// contains filtered or unexported fields
}

func ContextRouteMetric

func ContextRouteMetric(c context.Context) *RouteMetric

func NewRouteMetric

func NewRouteMetric(c context.Context, method, route string) (context.Context, *RouteMetric)

func (*RouteMetric) Start

func (t *RouteMetric) Start(c context.Context, name string) (context.Context, Span)

func (*RouteMetric) WithSpan

func (t *RouteMetric) WithSpan(ctx context.Context, name string, body func(context.Context) error) error

type Span

type Span interface {
	Finish()
}

func ContextSpan

func ContextSpan(c context.Context) Span

type StackFrame

type StackFrame struct {
	File string         `json:"file"`
	Line int            `json:"line"`
	Func string         `json:"function"`
	Code map[int]string `json:"code,omitempty"`
}