README

errbag - An error throttler for Go

Is your Go (golang) application running for long period of times or as a daemon? If the answer is yes, chances are that you might find errbag useful.

Errbag is a Go package that allows Go programs to pause for a predefined amount of time when too many errors happen.

Errors are usually unavoidable for programs or applications which are supposed to run continuously for long period of times. In these case, errors are dealt with and eventually logged. What if, all of a sudden, tens or hundreds of errors are raised each second? This usually indicates something troublesome is happening to the machine running the application. It could be the network being down or a disk partition being full but this obviously depends on the application. Anyway, in this case it would be advised not to log errors like crazy and keep on going but pause the application in order to let the sysadmin deal with the underlying problem. This is exactly to solve this problem that errbag has been created.

Installation and usage

Get the package first: go get github.com/Rolinh/errbag And import it into your project.

First thing needed is to create a new Errbag by invoking New() and then inflate it using Inflate(). From this point, you can record errors using Record(). This method optionally takes a callback function as argument. When too many errors are recorded, it will block for a defined amount of time before returning. When done, do not forget to Deflate() the Errbag (I would advise to call Deflate() in a defer statement).

Here is a full (stupid) example:

package main

import (
	"fmt"
	"os"

	"github.com/Rolinh/errbag"
)

func main() {
	var waitTime, errBagSize, leakInterval uint
	waitTime, errBagSize, leakInterval = 5, 60, 1000

	bag, err := errbag.New(waitTime, errBagSize, leakInterval)
	if err != nil {
		fmt.Fprintln(os.Stderr, "impossible to create a new errbag:", err)
		os.Exit(1)
	}
	bag.Inflate()
	defer bag.Deflate()

	// some function which potentially returns a non nil error
	// (use your imagination...)
	foo := func() error {
		var err error
		return err
	}

	// we do a lots of calls to foo() later on...
	for i := 0; i < 10000; i++ {
		bag.Record(foo(), func(status errbag.Status) {
			if status.State != errbag.StatusOK {
				// Damn, we are throttling for status.WaitTime time.
				// Take the appropriate action, like sending an email to the
				// sysadmin or whatever :)
				// This is obviously optional. If you don't care, simply pass
				// nil as a second argument to Record().
			}
		})
	}
}

Documentation

Overview

Package errbag implements an error rate based throttler. It can be used to limit function calls rate once a certain error rate threshold has been reached.

Index

• Constants
• type CallbackFunc
• type ErrBag
  • func New(waitTime, errBagSize, leakInterval uint) (*ErrBag, error)
  • func (eb ErrBag) Deflate()
  • func (eb ErrBag) Inflate()
  • func (eb ErrBag) Record(err error, callback CallbackFunc)
• type Status

Constants

const (
	// StatusThrottling indicates the errbag is throttling.
	StatusThrottling = iota

	// StatusOK indicates that all is well.
	StatusOK
)

Variables

This section is empty.

Functions

This section is empty.

Types

type CallbackFunc

type CallbackFunc func(status Status)

CallbackFunc is used as an argument to the Record() method.

type ErrBag

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

ErrBag is very effective at preventing an error rate to reach a certain threshold.

func New

func New(waitTime, errBagSize, leakInterval uint) (*ErrBag, error)

New creates a new ErrBag, for safety purpose. waitTime corresponds to the number of seconds to wait when the error rate threshold is reached. errBagSize is, in seconds, the size of the sliding window to consider for throttling. You can see it as the size of the errbag. The larger it is, the larger the window to consider for error rate is. Consider this value along with leakInterval. leakInterval corresponds to the time to wait, in milliseconds, before an error is discarded from the errbag. It must be equal or greater than 100, otherwise throttling will be ineffective.

func (ErrBag) Deflate

func (eb ErrBag) Deflate()

Deflate needs to be called when the errbag is of no use anymore. Calling Record() with a deflated errbag will induce a panic.

func (ErrBag) Inflate

func (eb ErrBag) Inflate()

Inflate needs to be called once to prepare the ErrBag. Once the ErrBag is not needed anymore, a proper call to Deflate() shall be made.

func (ErrBag) Record

func (eb ErrBag) Record(err error, callback CallbackFunc)

Record records an error if its value is non nil. It shall be called by any function returning an error in order to properly rate limit the errors produced. RecordError will wait for waitTime seconds if the error rate is too high. callback purpose is for the caller to be informed about the errbag status after an error has been recorded in order to help take the appropriate actions. nil can be passed if the caller is not interested in the status. Note that record will panic if called after Deflate() has been called.

type Status

type Status struct {
	// State indicates whether throttling had to be activated after an error
	// has been recorded (StatusThrottling) or if it was simply registered and
	// all is well (StatusOK).
	State int

	// WaitTime indicates for how long the Record() method will wait before
	// being available to record new errors.
	WaitTime uint
}

Status structure is used as argument to CallbackFunc. It indicates the the sate of the errbag after having recorded an error.