Documentation ¶
Overview ¶
Sawmill is an asynchronous, structured, log event handler.
Asynchronous: Sawmill does not block execution waiting for the log message to be delivered to the destination (e.g. STDOUT). Because of this asynchronous processing, it is critical that you add a `defer sawmill.Stop()` at the top of your `main()`. This will ensure that when the program exits, it waits for any pending log events to flush out to their destination.
Structured: Sawmill places a heavy emphasis on events with ancillary data. A log event (e.g. `sawmill.Error()`) should have a simple string that is an event description, such as "Image processing failed", and then a map or struct included with details on the event.
----
The base package provides a default logger that will send events to STDOUT or STDERR as appropriate. This default logger is shared by all consumers of the package.
Example ¶
package main import ( "github.com/phemmer/sawmill" ) type mystruct struct { Foo string Bar string Baz []byte List []int } func main() { defer sawmill.Stop() data := &mystruct{ Foo: "FOO", Bar: "BAR var", Baz: []byte("abc\000def"), List: []int{4, 5, 6}, } sawmill.Info("An event occurred", data) sawmill.Fatal("Whoops!", sawmill.Fields{"fu": "bar"}) }
Output:
Index ¶
- Constants
- func AddHandler(name string, handler Handler)
- func Alert(message string, fields ...interface{}) uint64
- func CheckPanic()
- func Critical(message string, fields ...interface{}) uint64
- func Debug(message string, fields ...interface{}) uint64
- func Emergency(message string, fields ...interface{}) uint64
- func Error(message string, fields ...interface{}) uint64
- func Event(level event.Level, message string, fields ...interface{}) uint64
- func Fatal(message string, fields ...interface{})
- func FilterHandler(handler Handler, filterFuncs ...filter.FilterFunc) *filter.FilterHandler
- func GetStackMinLevel() event.Level
- func GetSync() bool
- func Info(message string, fields ...interface{}) uint64
- func InitStdStreams()
- func InitStdSyslog() error
- func NewWriter(level event.Level) io.WriteCloser
- func Notice(message string, fields ...interface{}) uint64
- func RemoveHandler(name string, wait bool)
- func SendEvent(logEvent *event.Event) uint64
- func SetStackMinLevel(level event.Level)
- func SetSync(enabled bool)
- func Stop()
- func Sync(eventId uint64)
- func Warning(message string, fields ...interface{}) uint64
- type Fields
- type Handler
- type Logger
- func (logger *Logger) AddHandler(name string, handler Handler)
- func (logger *Logger) Alert(message string, fields ...interface{}) uint64
- func (logger *Logger) CheckPanic()
- func (logger *Logger) Critical(message string, fields ...interface{}) uint64
- func (logger *Logger) Debug(message string, fields ...interface{}) uint64
- func (logger *Logger) Emergency(message string, fields ...interface{}) uint64
- func (logger *Logger) Error(message string, fields ...interface{}) uint64
- func (logger *Logger) Event(level event.Level, message string, fields ...interface{}) uint64
- func (logger *Logger) Fatal(message string, fields ...interface{})
- func (logger *Logger) FilterHandler(handler Handler, filterFuncs ...filter.FilterFunc) *filter.FilterHandler
- func (logger *Logger) GetHandler(name string) Handler
- func (logger *Logger) GetStackMinLevel() event.Level
- func (logger *Logger) GetSync() bool
- func (logger *Logger) Info(message string, fields ...interface{}) uint64
- func (logger *Logger) InitStdStreams()
- func (logger *Logger) InitStdSyslog() error
- func (logger *Logger) NewWriter(level event.Level) io.WriteCloser
- func (logger *Logger) Notice(message string, fields ...interface{}) uint64
- func (logger *Logger) RemoveHandler(name string, wait bool)
- func (logger *Logger) SendEvent(logEvent *event.Event) uint64
- func (logger *Logger) SetStackMinLevel(level event.Level)
- func (logger *Logger) SetSync(enabled bool)
- func (logger *Logger) Stop()
- func (logger *Logger) Sync(eventId uint64)
- func (logger *Logger) Warning(message string, fields ...interface{}) uint64
Examples ¶
Constants ¶
const ( DebugLevel = event.Debug InfoLevel = event.Info NoticeLevel = event.Notice WarningLevel = event.Warning ErrorLevel = event.Error CriticalLevel = event.Critical AlertLevel = event.Alert EmergencyLevel = event.Emergency )
these are copied here for convenience
Variables ¶
This section is empty.
Functions ¶
func AddHandler ¶
AddHandler registers a new destination handler with the logger.
The name parameter is a unique identifier so that the handler can be targeted with RemoveHandler().
If a handler with the same name already exists, it will be replaced by the new one. During replacement, the function will block waiting for any pending events to be flushed to the old handler.
func Alert ¶
Alert generates an event at the alert level. It returns an event Id that can be used with Sync().
func CheckPanic ¶
func CheckPanic()
CheckPanic is used to check for panics and log them when encountered. The function must be executed via defer. CheckPanic will not halt the panic. After logging, the panic will be passed through.
func Critical ¶
Critical generates an event at the critical level. It returns an event Id that can be used with Sync().
func Debug ¶
Debug generates an event at the debug level. It returns an event Id that can be used with Sync().
func Emergency ¶
Emergency generates an event at the emergency level. It returns an event Id that can be used with Sync().
func Error ¶
Error generates an event at the error level. It returns an event Id that can be used with Sync().
func Event ¶
Event queues a message at the given level. Additional fields may be provided, which will be recursively copied at the time of the function call, and provided to the destination output handler. It returns an event Id that can be used with Sync().
func Fatal ¶
func Fatal(message string, fields ...interface{})
Fatal generates an event at the critical level, and then exits the program with status 1
func FilterHandler ¶
func FilterHandler(handler Handler, filterFuncs ...filter.FilterFunc) *filter.FilterHandler
FilterHandler is a convience wrapper for filter.New().
Example usage:
stdStreamsHandler := sawmill.GetHandler("stdStreams") stdStreamsHandler = sawmill.FilterHandler(stdStreamsHandler).LevelMin(sawmill.ErrorLevel) sawmill.AddHandler("stdStreams", stdStreamsHandler)
func GetStackMinLevel ¶
GetStackMinLevel gets the minimum level at which to include a stack trace in events.
func Info ¶
Info generates an event at the info level. It returns an event Id that can be used with Sync().
func InitStdStreams ¶
func InitStdStreams()
InitStdStreams is a convience function to register a STDOUT/STDERR handler with the logger.
The is automatically invoked on the default package level logger, and should not normally be called.
func InitStdSyslog ¶
func InitStdSyslog() error
InitStdSyslog is a convenience function to register a syslog handler with the logger.
The handler is added with the name 'syslog'
func NewWriter ¶
func NewWriter(level event.Level) io.WriteCloser
NewWriter returns an io.WriteCloser compatable object that can be used for traditional writing into sawmill.
The main use case for this is to redirect the stdlib log package into sawmill. For example:
log.SetOutput(sawmill.NewWriter(sawmill.InfoLevel)) log.SetFlags(0) // sawmill does its own formatting
func Notice ¶
Notice generates an event at the notice level. It returns an event Id that can be used with Sync().
func RemoveHandler ¶
RemoveHandler removes the named handler from the logger, preventing any further events from being sent to it. The wait parameter will result in the function blocking until all events queued for the handler have finished processing.
func SendEvent ¶
SendEvent queues the given event. The event's `Id` field will be updated with a value that can be used by Sync(). This value is also provided as the return value for convenience.
func SetStackMinLevel ¶
SetStackMinLevel sets the minimum level at which to include a stack trace in events.
func SetSync ¶
func SetSync(enabled bool)
SetSync controls synchronous event mode. When set to true, a function call to generate an event does not return until the event has been processed.
func Stop ¶
func Stop()
Stop removes all destinations on the logger, and waits for any pending events to flush to their destinations.
Types ¶
type Fields ¶
type Fields map[string]interface{}
Fields is a convenience type for passing ancillary data when generating events.
type Handler ¶
Handler represents a destination for sawmill to send events to. It responds to a single method, `Event`, which accepts the event to process. It must not return until the event has been fully processed.
func GetHandler ¶
GetHandler retrieves the handler with the given name. Returns nil if no such handler exists.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger is the core type in sawmill. The logger tracks a list of destinations, and when given an event, will asynchronously send that event to all registered destination handlers.
func DefaultLogger ¶
func DefaultLogger() *Logger
DefaultLogger returns a common *Logger object that is shared among all consumers of the package. It is used implicitly by all the package level helper function (Event, Emergency, etc)
func NewLogger ¶
func NewLogger() *Logger
NewLogger constructs a Logger. The new Logger will not have any registered handlers.
By default events will not include a stack trace. If any destination handler makes use of a stack trace, call SetStackMinLevel on the logger.
func (*Logger) AddHandler ¶
AddHandler registers a new destination handler with the logger.
The name parameter is a unique identifier so that the handler can be targeted with RemoveHandler().
If a handler with the same name already exists, it will be replaced by the new one. During replacement, the function will block waiting for any pending events to be flushed to the old handler.
func (*Logger) Alert ¶
Alert generates an event at the alert level. It returns an event Id that can be used with Sync().
func (*Logger) CheckPanic ¶
func (logger *Logger) CheckPanic()
CheckPanic is used to check for panics and log them when encountered. The function must be executed via defer. CheckPanic will not halt the panic. After logging, the panic will be passed through.
func (*Logger) Critical ¶
Critical generates an event at the critical level. It returns an event Id that can be used with Sync().
func (*Logger) Debug ¶
Debug generates an event at the debug level. It returns an event Id that can be used with Sync().
func (*Logger) Emergency ¶
Emergency generates an event at the emergency level. It returns an event Id that can be used with Sync().
func (*Logger) Error ¶
Error generates an event at the error level. It returns an event Id that can be used with Sync().
func (*Logger) Event ¶
Event queues a message at the given level. Additional fields may be provided, which will be recursively copied at the time of the function call, and provided to the destination output handler. It returns an event Id that can be used with Sync().
func (*Logger) Fatal ¶
Fatal generates an event at the critical level, and then exits the program with status 1
func (*Logger) FilterHandler ¶
func (logger *Logger) FilterHandler(handler Handler, filterFuncs ...filter.FilterFunc) *filter.FilterHandler
FilterHandler is a convience wrapper for filter.New().
Example usage:
stdStreamsHandler := logger.GetHandler("stdStreams") stdStreamsHandler = logger.FilterHandler(stdStreamsHandler).LevelMin(sawmill.ErrorLevel) logger.AddHandler("stdStreams", stdStreamsHandler)
func (*Logger) GetHandler ¶
GetHandler retrieves the handler with the given name. Returns nil if no such handler exists.
func (*Logger) GetStackMinLevel ¶
GetStackMinLevel gets the minimum level at which to include a stack trace in events.
func (*Logger) Info ¶
Info generates an event at the info level. It returns an event Id that can be used with Sync().
func (*Logger) InitStdStreams ¶
func (logger *Logger) InitStdStreams()
InitStdStreams is a convience function to register a STDOUT/STDERR handler with the logger.
The handler is added with the name 'stdStreams'
func (*Logger) InitStdSyslog ¶
InitStdSyslog is a convenience function to register a syslog handler with the logger.
The handler is added with the name 'syslog'
func (*Logger) NewWriter ¶
func (logger *Logger) NewWriter(level event.Level) io.WriteCloser
NewWriter returns an io.Writer compatable object that can be used for traditional writing into sawmill.
The main use case for this is to redirect the stdlib log package into sawmill. For example:
log.SetOutput(logger.NewWriter(sawmill.InfoLevel)) log.SetFlags(0) // sawmill does its own formatting
func (*Logger) Notice ¶
Notice generates an event at the notice level. It returns an event Id that can be used with Sync().
func (*Logger) RemoveHandler ¶
RemoveHandler removes the named handler from the logger, preventing any further events from being sent to it. The wait parameter will result in the function blocking until all events queued for the handler have finished processing.
func (*Logger) SendEvent ¶
SendEvent queues the given event. The event's `Id` field will be updated with a value that can be used by Sync(). This value is also provided as the return value for convenience.
func (*Logger) SetStackMinLevel ¶
SetStackMinLevel sets the minimum level at which to include a stack trace in events.
func (*Logger) SetSync ¶
SetSync controls synchronous event mode. When set to true, a function call to generate an event does not return until the event has been processed.
func (*Logger) Stop ¶
func (logger *Logger) Stop()
Stop removes all destination handlers on the logger, and waits for any pending events to flush out.
Directories ¶
Path | Synopsis |
---|---|
formatter
The formatter package is used to wrap an event with helper functions so it can be easily used in text templates.
|
The formatter package is used to wrap an event with helper functions so it can be easily used in text templates. |
handler
|
|
airbrake
The airbrake package provides a handler which sends events to the Airbrake error reporting service.
|
The airbrake package provides a handler which sends events to the Airbrake error reporting service. |
capture
The capture handler maintains a threadsafe slice of *event.Event.
|
The capture handler maintains a threadsafe slice of *event.Event. |
channel
The channel handler provides an unbuffered `chan *event.Event` onto which each recieved event is written.
|
The channel handler provides an unbuffered `chan *event.Event` onto which each recieved event is written. |
filter
The filter package provides a way to filter events from handlers.
|
The filter package provides a way to filter events from handlers. |
sentry
The sentry package provides a handler which sends events to the Sentry exception reporting service.
|
The sentry package provides a handler which sends events to the Sentry exception reporting service. |
splunk
The splunk package is an event handler responsible for sending events to Splunk via the HTTP API.
|
The splunk package is an event handler responsible for sending events to Splunk via the HTTP API. |
syslog
The syslog package is an event handler responsible for sending events to syslog.
|
The syslog package is an event handler responsible for sending events to syslog. |
writer
The writer package is an event handler responsible for sending events to a generic IO writer.
|
The writer package is an event handler responsible for sending events to a generic IO writer. |
The log package provides stdlib log interface compatability to sawmill.
|
The log package provides stdlib log interface compatability to sawmill. |