honeybadger

README

Honeybadger for Go

Go (golang) support for the ⚡ Honeybadger Exception Notifier. Receive instant notification of panics and errors in your Go applications.

Documentation and Support

For comprehensive documentation and support, check out our documentation site.

Supported Go Versions

This library supports the last two major Go releases, consistent with the Go team's release policy:

• Go 1.25.x
• Go 1.24.x

Older versions may work but are not officially supported or tested.

Changelog

See https://github.com/honeybadger-io/honeybadger-go/blob/master/CHANGELOG.md

Development

Pull requests are welcome. If you're adding a new feature, please submit an issue as a preliminary step; that way you can be (moderately) sure that your pull request will be accepted.

To contribute your code:

1. Fork it.
2. Create a topic branch git checkout -b my_branch
3. Commit your changes git commit -am "Boom"
4. Push to your branch git push origin my_branch
5. Send a pull request

Releasing

Releases are automated using release-please. When a PR is merged to master, a release PR is created (or updated) with version bumps and changelog entries based on conventional commits. Merging the release PR creates the GitHub release and tag.

License

This library is MIT licensed. See the LICENSE file in this repository for details.

Documentation

Index

• Constants
• Variables
• func BeforeEvent(handler func(event map[string]any) error)
• func BeforeNotify(handler func(notice *Notice) error)
• func ClearContext()
• func ClearEventContext()
• func Configure(c Configuration)
• func Event(eventType string, eventData map[string]any) error
• func Flush()
• func GetEnv[T any](key string, fallback ...any) T
• func Handler(h http.Handler) http.Handler
• func Monitor()
• func Notify(err interface{}, extra ...interface{}) (string, error)
• func SetContext(c Context)
• func SetEventContext(c Context)
• type Backend
  • func NewNullBackend() Backend
• type Batch
• type CGIData
• type Client
  • func New(c Configuration) *Client
  • func (client *Client) BeforeEvent(handler func(event map[string]any) error)
  • func (client *Client) BeforeNotify(handler func(notice *Notice) error)
  • func (client *Client) ClearContext()
  • func (client *Client) ClearEventContext()
  • func (client *Client) Configure(config Configuration)
  • func (client *Client) Event(eventType string, eventData map[string]any) error
  • func (client *Client) Flush()
  • func (client *Client) Handler(h http.Handler) http.Handler
  • func (client *Client) Monitor()
  • func (client *Client) Notify(err interface{}, extra ...interface{}) (string, error)
  • func (client *Client) SetContext(context Context)
  • func (client *Client) SetEventContext(context Context)
• type Configuration
• type Context
  • func (context Context) Update(other Context)
• type Error
  • func NewError(msg interface{}) Error
  • func (e Error) Error() string
  • func (e Error) Unwrap() error
• type ErrorClass
• type EventData
• type EventsWorker
  • func NewEventsWorker(cfg *Configuration) *EventsWorker
  • func (w *EventsWorker) AttemptSend() bool
  • func (w *EventsWorker) Flush()
  • func (w *EventsWorker) Push(e *eventPayload)
  • func (w *EventsWorker) Stop()
• type Feature
• type Fingerprint
  • func (f *Fingerprint) String() string
• type Frame
• type Logger
• type Notice
• type Params
• type Payload
• type Tags
• type TestBackend
  • func (b *TestBackend) Event(events []*eventPayload) error
  • func (b *TestBackend) GetEvents() []EventData
  • func (b *TestBackend) Notify(_ Feature, _ Payload) error

Constants

const VERSION = "0.9.0"

VERSION defines the version of the honeybadger package.

Variables

var (
	// client is a pre-defined "global" client.
	DefaultClient = New(Configuration{})

	// Config is a pointer to the global client's Config.
	Config = DefaultClient.Config

	// Notices is the feature for sending error reports.
	Notices = Feature{"notices"}

	// Events is the feature for sending events to Insights.
	Events = Feature{"events"}
)

var (
	ErrRateExceeded    = errors.New("Rate exceeded: slow down!")
	ErrPaymentRequired = errors.New("Payment required: expired trial or credit card?")
	ErrUnauthorized    = errors.New("Unauthorized: bad API key?")
)

Errors returned by the backend when unable to successfully handle payload.

var ErrEventDropped = errors.New("event dropped by handler")

Functions

func BeforeEvent

func BeforeEvent(handler func(event map[string]any) error)

BeforeEvent adds a callback function which is run before an event is sent to Honeybadger. If any function returns an error the event will be dropped, otherwise it will be sent.

func BeforeNotify

func BeforeNotify(handler func(notice *Notice) error)

BeforeNotify adds a callback function which is run before a notice is reported to Honeybadger. If any function returns an error the notification will be skipped, otherwise it will be sent.

func ClearContext

func ClearContext()

ClearContext clears all context data from the global client.

func ClearEventContext

func ClearEventContext()

ClearEventContext clears all event context data from the global client.

func Configure

func Configure(c Configuration)

Configure updates configuration of the global client.

func Event

func Event(eventType string, eventData map[string]any) error

Event sends a custom event to Honeybadger Insights. For example:

honeybadger.Event("user_login", map[string]any{
	"user_id": 123,
	"email":   "user@example.com",
})

func Flush

func Flush()

Flush blocks until all data (normally sent in the background) has been sent to the Honeybadger service.

func GetEnv

func GetEnv[T any](key string, fallback ...any) T

func Handler

func Handler(h http.Handler) http.Handler

Handler returns an http.Handler function which automatically reports panics to Honeybadger and then re-panics.

func Monitor

func Monitor()

Monitor is used to automatically notify Honeybadger service of panics which happen inside the current function. In order to monitor for panics, defer a call to Monitor. For example:

func main {
	defer honeybadger.Monitor()
	// Do risky stuff...
}

The Monitor function re-panics after the notification has been sent, so it's still up to the user to recover from panics if desired.

func Notify

func Notify(err interface{}, extra ...interface{}) (string, error)

Notify reports the error err to the Honeybadger service.

The first argument err may be an error, a string, or any other type in which case its formatted value will be used.

It returns a string UUID which can be used to reference the error from the Honeybadger service, and an error as a second argument.

func SetContext

func SetContext(c Context)

SetContext merges c Context into the Context of the global client.

func SetEventContext

func SetEventContext(c Context)

SetEventContext sets context data that will be merged into all events sent via Event(). Data passed directly to Event() takes precedence over context.

Types

type Backend

type Backend interface {
	Notify(feature Feature, payload Payload) error
	Event(events []*eventPayload) error
}

The Backend interface is implemented by the server type by default, but a custom implementation may be configured by the user.

func NewNullBackend

func NewNullBackend() Backend

NewNullBackend creates a backend which swallows all errors and does not send them to Honeybadger. This is useful for development and testing to disable sending unnecessary errors.

type Batch

type Batch struct {
	// contains filtered or unexported fields
}

type CGIData

type CGIData hash

CGIData stores variables from the server/request environment indexed by key. Header keys should be converted to upercase, all non-alphanumeric characters replaced with underscores, and prefixed with HTTP_. For example, the header "Content-Type" would become "HTTP_CONTENT_TYPE".

type Client

type Client struct {
	Config *Configuration
	// contains filtered or unexported fields
}

Client is the manager for interacting with the Honeybadger service. It holds the configuration and implements the public API.

func New

func New(c Configuration) *Client

New returns a new instance of Client.

func (*Client) BeforeEvent

func (client *Client) BeforeEvent(handler func(event map[string]any) error)

func (*Client) BeforeNotify

func (client *Client) BeforeNotify(handler func(notice *Notice) error)

BeforeNotify adds a callback function which is run before a notice is reported to Honeybadger. If any function returns an error the notification will be skipped, otherwise it will be sent.

func (*Client) ClearContext

func (client *Client) ClearContext()

ClearContext clears all context data.

func (*Client) ClearEventContext

func (client *Client) ClearEventContext()

ClearEventContext clears all event context data.

func (*Client) Configure

func (client *Client) Configure(config Configuration)

Configure updates the client configuration with the supplied config.

func (*Client) Event

func (client *Client) Event(eventType string, eventData map[string]any) error

func (*Client) Flush

func (client *Client) Flush()

Flush blocks until the worker has processed its queue.

func (*Client) Handler

func (client *Client) Handler(h http.Handler) http.Handler

Handler returns an http.Handler function which automatically reports panics to Honeybadger and then re-panics.

func (*Client) Monitor

func (client *Client) Monitor()

Monitor automatically reports panics which occur in the function it's called from. Must be deferred.

func (*Client) Notify

func (client *Client) Notify(err interface{}, extra ...interface{}) (string, error)

Notify reports the error err to the Honeybadger service.

func (*Client) SetContext

func (client *Client) SetContext(context Context)

SetContext updates the client context with supplied context.

func (*Client) SetEventContext

func (client *Client) SetEventContext(context Context)

SetEventContext updates the client event context with supplied context.

type Configuration

type Configuration struct {
	APIKey                string
	Root                  string
	Env                   string
	Hostname              string
	Endpoint              string
	Sync                  bool
	Timeout               time.Duration
	Logger                Logger
	Backend               Backend
	Context               context.Context
	EventsBatchSize       int
	EventsThrottleWait    time.Duration
	EventsTimeout         time.Duration
	EventsMaxQueueSize    int
	EventsMaxRetries      int
	EventsDropLogInterval time.Duration
}

Configuration manages the configuration for the client.

type Context

type Context hash

Context is used to send extra data to Honeybadger.

func (Context) Update

func (context Context) Update(other Context)

Update applies the values in other Context to context.

type Error

type Error struct {
	Message string
	Class   string
	Stack   []*Frame
	// contains filtered or unexported fields
}

Error provides more structured information about a Go error.

func NewError

func NewError(msg interface{}) Error

func (Error) Error

func (e Error) Error() string

func (Error) Unwrap

func (e Error) Unwrap() error

type ErrorClass

type ErrorClass struct {
	Name string
}

ErrorClass represents the class name of the error which is sent to Honeybadger.

type EventData

type EventData struct {
	EventType string
	Data      map[string]any
}

type EventsWorker

type EventsWorker struct {
	// contains filtered or unexported fields
}

func NewEventsWorker

func NewEventsWorker(cfg *Configuration) *EventsWorker

func (*EventsWorker) AttemptSend

func (w *EventsWorker) AttemptSend() bool

func (*EventsWorker) Flush

func (w *EventsWorker) Flush()

func (*EventsWorker) Push

func (w *EventsWorker) Push(e *eventPayload)

func (*EventsWorker) Stop

func (w *EventsWorker) Stop()

type Feature

type Feature struct {
	Endpoint string
}

Feature references a resource provided by the API service. Its Endpoint maps to the collection endpoint of the /v1 API.

type Fingerprint

type Fingerprint struct {
	Content string
}

Fingerprint represents the fingerprint of the error, which controls grouping in Honeybadger.

func (*Fingerprint) String

func (f *Fingerprint) String() string

type Frame

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

Frame represent a stack frame inside of a Honeybadger backtrace.

type Logger

type Logger interface {
	Printf(format string, v ...interface{})
}

The Logger interface is implemented by the standard log package and requires a limited subset of the interface implemented by log.Logger.

type Notice

type Notice struct {
	APIKey       string
	Error        Error
	Token        string
	ErrorMessage string
	ErrorClass   string
	Tags         []string
	Hostname     string
	Env          string
	Backtrace    []*Frame
	ProjectRoot  string
	Context      Context
	Params       Params
	CGIData      CGIData
	URL          string
	Fingerprint  string
}

Notice is a representation of the error which is sent to Honeybadger, and implements the Payload interface.

type Params

type Params url.Values

Params stores the form or url values from an HTTP request.

type Payload

type Payload interface {
	// contains filtered or unexported methods
}

The Payload interface is implemented by any type which can be handled by the Backend interface.

type Tags

type Tags []string

Tags represents tags of the error which is classified errors in Honeybadger.

type TestBackend

type TestBackend struct {
	Events []EventData
	// contains filtered or unexported fields
}

func (*TestBackend) Event

func (b *TestBackend) Event(events []*eventPayload) error

func (*TestBackend) GetEvents

func (b *TestBackend) GetEvents() []EventData

func (*TestBackend) Notify

func (b *TestBackend) Notify(_ Feature, _ Payload) error