Documentation ¶
Overview ¶
Package grip provides a flexible logging package for basic Go programs. Drawing inspiration from Go and Python's standard library logging, as well as systemd's journal service, and other logging systems, Grip provides a number of very powerful logging abstractions in one high-level package.
Logging Instances ¶
The central type of the grip package is the Journaler type, instances of which provide distinct log capturing system. For ease, following from the Go standard library, the grip package provides parallel public methods that use an internal "standard" Jouernaler instance in the grip package, which has some defaults configured and may be sufficient for many use cases.
Output ¶
The send.Sender interface provides a way of changing the logging backend, and the send package provides a number of alternate implementations of logging systems, including: systemd's journal, logging to standard output, logging to a file, and generic syslog support.
Messages ¶
The message.Composer interface is the representation of all messages. They are implemented to provide a raw structured form as well as a string representation for more conentional logging output. Furthermore they are intended to be easy to produce, and defer more expensive processing until they're being logged, to prevent expensive operations producing messages that are below threshold.
Catch Logging ¶
Logging helpers for catching and logging error messages. Helpers exist for the following levels, with helpers defined both globally for the global logger and for Journaler logging objects.
Basic Logging ¶
Loging helpers exist for the following levels:
Emergency + (fatal/panic) Alert + (fatal/panic) Critical + (fatal/panic) Error + (fatal/panic) Warning Notice Info Debug
These methods accept both strings (message content,) or types that implement the message.MessageComposer interface. Composer types make it possible to delay generating a message unless the logger is over the logging threshold. Use this to avoid expensive serialization operations for suppressed logging operations.
All levels also have additional methods with `ln` and `f` appended to the end of the method name which allow Println() and Printf() style functionality. You must pass printf/println-style arguments to these methods.
Error Catcher ¶
The MutiCatcher type makes it possible to collect from a group of operations and then aggregate them as a single error.
Conditional Logging ¶
The Conditional logging methods take two arguments, a Boolean, and a message argument. Messages can be strings, objects that implement the MessageComposer interface, or errors. If condition boolean is true, the threshold level is met, and the message to log is not an empty string, then it logs the resolved message.
Use conditional logging methods to potentially suppress log messages based on situations orthogonal to log level, with "log sometimes" or "log rarely" semantics. Combine with MessageComposers to to avoid expensive message building operations.
Index ¶
- func Alert(msg interface{})
- func AlertWhen(conditional bool, m interface{})
- func AlertWhenf(conditional bool, msg string, args ...interface{})
- func AlertWhenln(conditional bool, msg ...interface{})
- func Alertf(msg string, a ...interface{})
- func Alertln(a ...interface{})
- func CatchAlert(err error)
- func CatchCritical(err error)
- func CatchDebug(err error)
- func CatchEmergency(err error)
- func CatchEmergencyFatal(err error)
- func CatchEmergencyPanic(err error)
- func CatchError(err error)
- func CatchInfo(err error)
- func CatchLog(l level.Priority, err error)
- func CatchNotice(err error)
- func CatchWarning(err error)
- func Critical(msg interface{})
- func CriticalWhen(conditional bool, m interface{})
- func CriticalWhenf(conditional bool, msg string, args ...interface{})
- func CriticalWhenln(conditional bool, msg ...interface{})
- func Criticalf(msg string, a ...interface{})
- func Criticalln(a ...interface{})
- func Debug(msg interface{})
- func DebugWhen(conditional bool, m interface{})
- func DebugWhenf(conditional bool, msg string, args ...interface{})
- func DebugWhenln(conditional bool, msg ...interface{})
- func Debugf(msg string, a ...interface{})
- func Debugln(a ...interface{})
- func Emergency(msg interface{})
- func EmergencyFatal(msg interface{})
- func EmergencyFatalf(msg string, a ...interface{})
- func EmergencyFatalln(a ...interface{})
- func EmergencyPanic(msg interface{})
- func EmergencyPanicf(msg string, a ...interface{})
- func EmergencyPanicln(a ...interface{})
- func EmergencyWhen(conditional bool, m interface{})
- func EmergencyWhenf(conditional bool, msg string, args ...interface{})
- func EmergencyWhenln(conditional bool, msg ...interface{})
- func Emergencyf(msg string, a ...interface{})
- func Emergencyln(a ...interface{})
- func Error(msg interface{})
- func ErrorWhen(conditional bool, m interface{})
- func ErrorWhenf(conditional bool, msg string, args ...interface{})
- func ErrorWhenln(conditional bool, msg ...interface{})
- func Errorf(msg string, a ...interface{})
- func Errorln(a ...interface{})
- func GetSender() send.Sender
- func Info(msg interface{})
- func InfoWhen(conditional bool, message interface{})
- func InfoWhenf(conditional bool, msg string, args ...interface{})
- func InfoWhenln(conditional bool, msg ...interface{})
- func Infof(msg string, a ...interface{})
- func Infoln(a ...interface{})
- func Log(l level.Priority, msg interface{})
- func LogWhen(conditional bool, l level.Priority, m interface{})
- func LogWhenf(conditional bool, l level.Priority, msg string, args ...interface{})
- func LogWhenln(conditional bool, l level.Priority, msg ...interface{})
- func Logf(l level.Priority, msg string, a ...interface{})
- func Logln(l level.Priority, a ...interface{})
- func Name() string
- func Notice(msg interface{})
- func NoticeWhen(conditional bool, m interface{})
- func NoticeWhenf(conditional bool, msg string, args ...interface{})
- func NoticeWhenln(conditional bool, msg ...interface{})
- func Noticef(msg string, a ...interface{})
- func Noticeln(a ...interface{})
- func SetName(name string)
- func SetSender(s send.Sender) error
- func Warning(msg interface{})
- func WarningWhen(conditional bool, m interface{})
- func WarningWhenf(conditional bool, msg string, args ...interface{})
- func WarningWhenln(conditional bool, msg ...interface{})
- func Warningf(msg string, a ...interface{})
- func Warningln(a ...interface{})
- type Catcher
- type Journaler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AlertWhenf ¶
func AlertWhenln ¶
func AlertWhenln(conditional bool, msg ...interface{})
func CatchAlert ¶
func CatchAlert(err error)
func CatchCritical ¶
func CatchCritical(err error)
func CatchDebug ¶
func CatchDebug(err error)
func CatchEmergency ¶
func CatchEmergency(err error)
func CatchEmergencyFatal ¶
func CatchEmergencyFatal(err error)
func CatchEmergencyPanic ¶
func CatchEmergencyPanic(err error)
func CatchError ¶
func CatchError(err error)
func CatchNotice ¶
func CatchNotice(err error)
func CatchWarning ¶
func CatchWarning(err error)
func CriticalWhen ¶
func CriticalWhen(conditional bool, m interface{})
func CriticalWhenf ¶
func CriticalWhenln ¶
func CriticalWhenln(conditional bool, msg ...interface{})
func Criticalln ¶
func Criticalln(a ...interface{})
func DebugWhenf ¶
func DebugWhenln ¶
func DebugWhenln(conditional bool, msg ...interface{})
func EmergencyFatal ¶
func EmergencyFatal(msg interface{})
func EmergencyFatalf ¶
func EmergencyFatalf(msg string, a ...interface{})
func EmergencyFatalln ¶
func EmergencyFatalln(a ...interface{})
func EmergencyPanic ¶
func EmergencyPanic(msg interface{})
func EmergencyPanicf ¶
func EmergencyPanicf(msg string, a ...interface{})
func EmergencyPanicln ¶
func EmergencyPanicln(a ...interface{})
func EmergencyWhen ¶
func EmergencyWhen(conditional bool, m interface{})
func EmergencyWhenf ¶
func EmergencyWhenln ¶
func EmergencyWhenln(conditional bool, msg ...interface{})
func Emergencyf ¶
func Emergencyf(msg string, a ...interface{})
func Emergencyln ¶
func Emergencyln(a ...interface{})
func ErrorWhenf ¶
func ErrorWhenln ¶
func ErrorWhenln(conditional bool, msg ...interface{})
func GetSender ¶
GetSender returns the current Journaler's sender instance. Use this in combination with SetSender to have multiple Journaler instances backed by the same send.Sender instance.
func InfoWhenln ¶
func InfoWhenln(conditional bool, msg ...interface{})
func NoticeWhen ¶
func NoticeWhen(conditional bool, m interface{})
func NoticeWhenf ¶
func NoticeWhenln ¶
func NoticeWhenln(conditional bool, msg ...interface{})
func SetName ¶
func SetName(name string)
SetName declare a name string for the logger, including in the logging message. Typically this is included on the output of the command.
func SetSender ¶
SetSender swaps send.Sender() implementations in a logging instance. Calls the Close() method on the existing instance before changing the implementation for the current instance.
func WarningWhen ¶
func WarningWhen(conditional bool, m interface{})
func WarningWhenf ¶
func WarningWhenln ¶
func WarningWhenln(conditional bool, msg ...interface{})
Types ¶
type Catcher ¶
type Catcher interface { Add(error) Extend([]error) Len() int HasErrors() bool String() string Resolve() error Errors() []error }
Catcher is an interface for an error collector for use when implementing continue-on-error semantics in concurrent operations. There are three different Catcher implementations provided by this package that differ *only* in terms of the string format returned by String() (and also the format of the error returned by Resolve().)
If you do not use github.com/pkg/errors to attach errors, the implementations are usually functionally equivalent. The Extended variant formats the errors using the "%+v" (which returns a full stack trace with pkg/errors,) the Simple variant uses %s (which includes all the wrapped context,) and the basic catcher calls error.Error() (which should be equvalent to %s for most error implementations.)
func NewBasicCatcher ¶
func NewBasicCatcher() Catcher
NewBasicCatcher collects error messages and formats them using a new-line separated string of the output of error.Error()
func NewCatcher ¶
func NewCatcher() Catcher
NewCatcher returns a Catcher instance that you can use to capture error messages and aggregate the errors. For consistency with earlier versions NewCatcher is the same as NewExtendedCatcher()
DEPRECATED: use one of the other catcher implementations. See the documentation for the Catcher interface for most implementations.
func NewExtendedCatcher ¶
func NewExtendedCatcher() Catcher
NewExtendedCatcher collects error messages and formats them using a new-line separated string of the extended string format of the error message (e.g. %+v).
func NewSimpleCatcher ¶
func NewSimpleCatcher() Catcher
NewSimpleCatcher collects error messages and formats them using a new-line separated string of the string format of the error message (e.g. %s).
type Journaler ¶
type Journaler interface { Name() string SetName(string) // Methods to access the underlying message sending backend. GetSender() send.Sender SetSender(send.Sender) error // Specify a log level as an argument rather than a method // name. Log(level.Priority, interface{}) Logf(level.Priority, string, ...interface{}) Logln(level.Priority, ...interface{}) LogWhen(bool, level.Priority, interface{}) LogWhenf(bool, level.Priority, string, ...interface{}) LogWhenln(bool, level.Priority, ...interface{}) // Log a message (the contents of the error,) only if the // error is non-nil. These are redundant to the similar base // methods. (e.g. Alert and CatchAlert have the same behavior.) CatchLog(level.Priority, error) CatchEmergency(error) CatchAlert(error) CatchCritical(error) CatchError(error) CatchWarning(error) CatchNotice(error) CatchInfo(error) CatchDebug(error) // Emergency methods have "panic" and "fatal" variants that // call panic or os.Exit(1). It is impossible for "Emergency" // to be below threshold, however, if the message isn't // loggable (e.g. error is nil, or message is empty,) these // methods will not panic/error. CatchEmergencyFatal(error) CatchEmergencyPanic(error) EmergencyFatal(interface{}) EmergencyFatalf(string, ...interface{}) EmergencyFatalln(...interface{}) EmergencyPanic(interface{}) EmergencyPanicf(string, ...interface{}) EmergencyPanicln(...interface{}) Emergency(interface{}) Emergencyf(string, ...interface{}) Emergencyln(...interface{}) EmergencyWhen(bool, interface{}) EmergencyWhenf(bool, string, ...interface{}) EmergencyWhenln(bool, ...interface{}) Alert(interface{}) Alertf(string, ...interface{}) Alertln(...interface{}) AlertWhen(bool, interface{}) AlertWhenf(bool, string, ...interface{}) AlertWhenln(bool, ...interface{}) Critical(interface{}) Criticalf(string, ...interface{}) Criticalln(...interface{}) CriticalWhen(bool, interface{}) CriticalWhenf(bool, string, ...interface{}) CriticalWhenln(bool, ...interface{}) Error(interface{}) Errorf(string, ...interface{}) Errorln(...interface{}) ErrorWhen(bool, interface{}) ErrorWhenf(bool, string, ...interface{}) ErrorWhenln(bool, ...interface{}) Warning(interface{}) Warningf(string, ...interface{}) Warningln(...interface{}) WarningWhen(bool, interface{}) WarningWhenf(bool, string, ...interface{}) WarningWhenln(bool, ...interface{}) Notice(interface{}) Noticef(string, ...interface{}) Noticeln(...interface{}) NoticeWhen(bool, interface{}) NoticeWhenf(bool, string, ...interface{}) NoticeWhenln(bool, ...interface{}) Info(interface{}) Infof(string, ...interface{}) Infoln(...interface{}) InfoWhen(bool, interface{}) InfoWhenf(bool, string, ...interface{}) InfoWhenln(bool, ...interface{}) Debug(interface{}) Debugf(string, ...interface{}) Debugln(...interface{}) DebugWhen(bool, interface{}) DebugWhenf(bool, string, ...interface{}) DebugWhenln(bool, ...interface{}) }
Journaler describes the public interface of the the Grip interface. Used to enforce consistency between the grip and logging packages.
func NewJournaler ¶
NewJournaler creates a new Journaler instance. The Sender method is a non-operational bootstrap method that stores default and threshold types, as needed. You must use SetSender() or the UseSystemdLogger(), UseNativeLogger(), or UseFileLogger() methods to configure the backend.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
The current vendoring solution supports both new and old style vendoring, via a trick: We commit all vendored code to the "vendor" directory, and then, if we're on a version/deployment of go that doesn't support new style vendoring, we symlink to "build/vendor/src" and add "build/vendor" to the gopath, which the render-gopath program generates inside of the makefile.
|
The current vendoring solution supports both new and old style vendoring, via a trick: We commit all vendored code to the "vendor" directory, and then, if we're on a version/deployment of go that doesn't support new style vendoring, we symlink to "build/vendor/src" and add "build/vendor" to the gopath, which the render-gopath program generates inside of the makefile. |
vendoring
Package vendoring provides a several variables used in vendoring buildscripts and function that reports (without any external dependencies) if the current environment requires legacy-style vendoring, or if its safe to use new-style vendoring.
|
Package vendoring provides a several variables used in vendoring buildscripts and function that reports (without any external dependencies) if the current environment requires legacy-style vendoring, or if its safe to use new-style vendoring. |
Package level defines a Priority type and some conversion methods for a 7-tiered logging level schema, which mirror syslog and system's logging levels.
|
Package level defines a Priority type and some conversion methods for a 7-tiered logging level schema, which mirror syslog and system's logging levels. |
Package logging provides the primary implementation of the Journaler interface (which is cloned in public functions in the grip interface itself.) Basic Logging Loging helpers exist for the following levels: Emergency + (fatal/panic) Alert + (fatal/panic) Critical + (fatal/panic) Error + (fatal/panic) Warning Notice Info Debug
|
Package logging provides the primary implementation of the Journaler interface (which is cloned in public functions in the grip interface itself.) Basic Logging Loging helpers exist for the following levels: Emergency + (fatal/panic) Alert + (fatal/panic) Critical + (fatal/panic) Error + (fatal/panic) Warning Notice Info Debug |
package message defines the Composer interface and a handful of implementations which represent the structure for messages produced by grip.
|
package message defines the Composer interface and a handful of implementations which represent the structure for messages produced by grip. |
Package recovery provides a number of grip-integrated panic handling tools for capturing and responding to panics using grip loggers.
|
Package recovery provides a number of grip-integrated panic handling tools for capturing and responding to panics using grip loggers. |
Call Site Sender Call site loggers provide a way to record the line number and file name where the logging call was made, which is particularly useful in tracing down log messages.
|
Call Site Sender Call site loggers provide a way to record the line number and file name where the logging call was made, which is particularly useful in tracing down log messages. |