README
¶
Smart Logrus Hooks
Logrus is a popular structured logger that allows to add hooks that are invoked for every message. These hooks can be used to send the messages to remote tracking and reporting system. Things may go wrong when talking to remote systems, like delays and errors.
The hooks from this package are decorators that help to deal with:
- Transient errors
- Excessive logging messages
- Slow transmission times
Setup
The examples will use the syslog hook to send messages to syslog daemon. The setup looks like this:
import (
"log/syslog"
"github.com/misho-kr/logrus-hooks"
"github.com/sirupsen/logrus"
lSyslog "github.com/sirupsen/logrus/hooks/syslog"
)
func init() {
// create a hook to be added to an instance of logger
hook, err := NewSyslogHook("udp", "server.fqdn:514", syslog.LOG_DEBUG, "")
}
From here additional hooks can be added for enhanced logging functionality.
Retry with backoff
Prevent transient errors from procesing the log messages with retries
log.AddHook(RetryHook(
hook,
100 * time.Millisecond, // delay between retries
hooks.Retries(3), // retry 3 times
hooks.FactorPct(100), // increase delay by 100% between retries
hooks.JitterPct(10), // jitter of 10% to the delay between retries
))
Rate limits
Put a cap on the number of logging messages per time interval
log.AddHook(RateLimitHook(
hook,
hooks.PerSecond(10), // 10 messages per second
hooks.Burst(20), // burst of 20 messages allowed
))
Asynchronous execution
Fire the hook in separate goroutine to avoid blocking the logger and main application
log.AddHook(AsyncHook(
hook,
hooks.Senders(10), // 10 goroutines to send messages
hooks.BoostSenders(20), // up to 20 additional goroutines when needed
))
Documentation
¶
Overview ¶
Package hooks provides several useful Logrus hooks
These hooks are used as decorators of other hooks and provide enhanced functionality:
- retry transmission with exponential backoff and jitter
- rate limits on the number of logging messages
- asynchronous execution
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrBufferFull is returned by `Fire` when the async hook can not take any more messages ErrBufferFull error // ErrNotRunning is returned when `Fire` is called before the async hook is started ErrNotRunning error )
Functions ¶
func RateLimitHook ¶
func RateLimitHook(next logrus.Hook, opts ...RateLimitOption) logrus.Hook
RateLimitHook creates a Logrus hook that enforces a rate limit on the logged messages
Types ¶
type AsyncOption ¶
type AsyncOption func(conf *asyncParams)
AsyncOption is a functional option to update the async hook configuration
func BoostSenders ¶
func BoostSenders(n uint32) AsyncOption
BoostSenders sets the number of boost senders goroutines of the new hook
func BufferLen ¶
func BufferLen(n uint32) AsyncOption
BufferLen sets the maximum number of messages that can be queued for transmission
func Senders ¶
func Senders(n uint32) AsyncOption
Senders sets the number of senders goroutines of the new hook
type Chain ¶
type Chain interface {
logrus.Hook
// Next is the element of the chain that follows this one
Next() logrus.Hook
}
Chain is a single-linked list of hooks that work together one after another
type ChainElement ¶
type ChainElement struct {
// contains filtered or unexported fields
}
ChainElement is a partial implementation of Chain interface that provides delegation
This type has `Next` method to access the next hook in the chain of hooks. It does not have `Fire` and `Levels` methods, they have to be implemented by the custom hooks.
func (*ChainElement) Next ¶
func (el *ChainElement) Next() logrus.Hook
Next is an accessor to the next element of the Chain
type ChainImpl ¶
type ChainImpl struct {
ChainElement
}
ChainImpl is a partial implementation of Chain interface that has Level method
This type provides `Levels` method which simply delegates the call to the next hook in the chain. This is the expected behavior of hooks that implement some custom action but do not care about the log level and let someone decide whether hook should fire or not.
type RateLimitOption ¶
type RateLimitOption func(conf *rateLimit)
RateLimitOption is a functional option to update the rate limit hook configuration
func Burst ¶
func Burst(n int) RateLimitOption
Burst sets the maximum number of messages that can be logged per second in a burst
func PerSecond ¶
func PerSecond(n int) RateLimitOption
PerSecond sets the maximum number of messages that can be logged per second
type RetryOption ¶
type RetryOption func(conf *backoff)
RetryOption is a functional option to update the retry hook configuration
func FactorPct ¶
func FactorPct(n int64) RetryOption
FactorPct sets the increase (in percents of the delay) that will be added to the delay after each retry
func JitterPct ¶
func JitterPct(n int64) RetryOption
JitterPct sets a random delay (in percents of the delay) that will be added to each retry
type RunningHook ¶
type RunningHook interface {
logrus.Hook
// IsRunning queries the state of the hook
IsRunning() bool
// Start prepares the hook to be able to send messages
Start() error
// Stop transitions the hook to a state in which it does not send messages
Stop() error
}
RunningHook is a Logrus hook that can be started and stopped
func AsyncHook ¶
func AsyncHook(next logrus.Hook, opts ...AsyncOption) RunningHook
AsyncHook creates a Logrus hook that uses goroutines to invoke the next hook
Source Files