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 ¶
const ( // StatusThrottling indicates the errbag is throttling. StatusThrottling = iota // StatusOK indicates that all is well. StatusOK )
Variables ¶
Functions ¶
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 ¶
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.
Directories
Path | Synopsis |
---|---|