README
¶
====================================
``grip`` -- A Golang Logging Library
====================================
Overview
--------
Grip is a high level logging and message system for providing a single
solution for structured logging, notification, and message sending.
#. Provide a common logging interface with support for multiple
output/messaging backends.
#. Provides some simple methods for errors, particularly when
you want to accumulate and then return errors.
#. Provides tools for collecting structured logging information.
*You just get a grip, folks.*
Use
---
``grip`` declares its dependencies via go modules. The top level ``grip``
package provides global logging functions that use a global logging
interface. You can also use the logging package to produce logger objects with
the same interface to avoid relying on a global logger.
Grip is available under the terms of the Apache License (v2.)
Design
------
Interface
~~~~~~~~~
Grip provides three main interfaces:
- The ``send.Sender`` interfaces which implements sending messages to various
output sources. Provides sending as well as the ability to support error
handling, and message formating support.
- The ``message.Composer`` which wraps messages providing both "string"
formating as well as a "raw" serialized approach.
- The ``grip.Journaler`` interface provides a high level logging interface,
and is mirrored in the package's public interface as a defult logger.
Goals
~~~~~
- Provide robust high-level abstractions for applications to manage messaging,
logging, and metrics collection.
- Integrate with other logging systems (e.g. standard library logging,
standard output of subprocesses, other libraries, etc.)
- Minimize operational complexity and dependencies for having robust logging
(e.g. make it possible to log effectively from within a program without
requiring log relays or collection agents.)
Development
-----------
Future Work
~~~~~~~~~~~
Grip is relatively stable, though there are additional features and areas of
development:
- structured metrics collection. This involves adding a new interface as a
superset of the Composer interface, and providing ways of filtering these
messages out to provide better tools for collecting diagnostic data from
applications.
- additional Sender implementations to support additional output formats and
needs.
- better integration with recent development in error wrapping in the go
standard library.
If you encounter a problem please feel free to create a github issue or open a
pull request.
History
~~~~~~~
Grip originated as a personal project, and became the default logging and
messaging tool for `Evergreen <https://github.com/evergreen-ci/>`_ and related
projects at MongoDB's release infrastructure developer productivity
organization.
This fork removes some legacy components and drops support older versions of
Golang, thereby adding support for modules.
Features
--------
Output Formats
~~~~~~~~~~~~~~
Grip supports a number of different logging output backends:
- systemd's journal (linux-only)
- syslog (unix-only)
- writing messages to standard output.
- writing messages to a file.
- sending messages to a slack's channel
- sending messages to a user via XMPP (jabber.)
- sending a desktop notification
- sending an email.
- sending log output.
- create a tweet.
See the documentation of the `Sender interface
<https://godoc.org/github.com/tychoish/grip/send#Sender>`_ for more
information on building new senders. The `base sender implementation
<https://godoc.org/github.com/tychoish/grip/send#Base>`_ implements most of
the interface, except for the Send method.
In addition to a collection of useful output implementations, grip also
provides tools for managing output including:
- the `multi sender
<https://godoc.org/cdr.dev/grip/send#NewConfiguredMultiSender>`_
for combining multiple senders to "tee" the output together,
- the `buffering sender
<https://godoc.org/cdr.dev/grip/send#NewBufferedSender>`_ for
wrapping a sender with a buffer that will batch messages after reciving a
specified number of messages, or on a specific interval.
- the `io.Writer
<https://godoc.org/cdr.dev/grip/send#WriterSender>`_ to convert a
sender implementation to an io.Writer, to be able to use grip fundamentals
in situations that call for ``io.Writers`` (e.g. the output of
subprocesses,.
- the `WrapWriter
<https://godoc.org/cdr.dev/grip/send#WrapWriter>`_ to use an
arbitrary ``io.Writer`` interface as a sender.
Logging
~~~~~~~
Provides a fully featured level-based logging system with multiple
backends (e.g. send.Sender). By default logging messages are printed
to standard output, but backends exists for many possible targets. The
interface for logging is provided by the Journaler interface.
By default ``grip.std`` defines a standard global instances
that you can use with a set of ``grip.<Level>`` functions, or you can
create your own ``Journaler`` instance and embed it in your own
structures and packages.
Defined helpers exist for the following levels/actions:
- ``Debug``
- ``Info``
- ``Notice``
- ``Warning``
- ``Error``
- ``Critical``
- ``Alert``
- ``Emergency``
- ``EmergencyPanic``
- ``EmergencyFatal``
Helpers ending with ``Panic`` call ``panic()`` after logging the message
message, and helpers ending with ``Fatal`` call ``os.Exit(1)`` after logging
the message. These are primarily for handling errors in your main() function
and should be used sparingly, if at all, elsewhere.
Sender instances have a notion of "default" log levels and thresholds, which
provide the basis for verbosity control and sane default behavior. The default
level defines the priority/level of any message with an invalid priority
specified. The threshold level, defines the minimum priority or level that
``grip`` sends to the logging system. It's not possible to suppress the
highest log level, ``Emergency`` messages will always log.
``Journaler`` objects have additional methods (also
available as functions in the ``grip`` package to manage and configure the
instance.
Error Collector for "Continue on Error" Semantics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to do something other than ignore or simply log errors, but don't
want to abort after an error, the `Catcher Interface
<https://godoc.org/cdr.dev/grip#Catcher>`_ provides a threadsafe
way of aggregating errors. Consider: ::
func doStuff(dirname string) (error) {
files, err := ioutil.ReadDir(dirname)
if err != nil {
// should abort here because we shouldn't continue.
return err
}
catcher := grip.NewCatcher()t
for _, f := range files {
err = doStuffToFile(f.Name())
catcher.Add(err)
}
return catcher.Resolve()
}
Grip provides several error catchers (which are independent of the logging
infrastructure.) They are Basic, Simple, and Extended. These variants differ
on how the collected errors are represented in the final error object. Basic
uses the ``Error()`` method of component errors, Simple users
``fmt.Sprintf("%s", err)`` and Extended users ``fmt.Sprintf("%+v",
err)``. There are also Timestamp methods that annotate all errors with a
timestamp of when the error was collected to improve debugability in longer
running asynchronous contexts: these collectors rely on ``WrapErrorTime`` to
annotate the timestamp, which may be useful in other contexts.
Conditional Logging
~~~~~~~~~~~~~~~~~~~
``grip`` incldues support for conditional logging, so that you can
only log a message in certain situations, by adding a Boolean argument
to the logging call. Use this to implement "log sometimes" messages to
minimize verbosity without complicating the calling code around the
logging, or simplify logging call sites. These methods have a ``<Level>When```
format.
This is syntactic sugar around the `message.When
<https://godoc.org/cdr.dev/grip/message#When>`_ message type, but
can reduce a lot of nesting and call-site complexity.
Composed Logging
~~~~~~~~~~~~~~~~
If the production of the log message is resource intensive or
complicated, you may wish to use a "composed logging," which delays
the generation of the log message from the logging call site to the
message propagation, to avoid generating the log message unless
necessary. Rather than passing the log message as a string, pass the
logging function an instance of a type that implements the
``Composer`` interface.
Grip uses composers internally, but you can pass composers directly to
any of the basic logging method (e.g. ``Info()``, ``Debug()``) for
composed logging.
Grip includes a number of message types, including those that collect
system information, process information, stacktraces, or simple
user-specified structured information.
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.
Basic Logging ¶
Loging helpers exist for the following levels:
Emergency + (fatal/panic) Alert Critical Error 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.
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.
Error Catcher ¶
The MutiCatcher type makes it possible to collect from a group of operations and then aggregate them as a single error.
Index ¶
- func Alert(msg interface{})
- func AlertWhen(conditional bool, m interface{})
- func Alertf(msg string, a ...interface{})
- func Alertln(a ...interface{})
- func Critical(msg interface{})
- func CriticalWhen(conditional bool, m interface{})
- func Criticalf(msg string, a ...interface{})
- func Criticalln(a ...interface{})
- func Debug(msg interface{})
- func DebugWhen(conditional bool, m interface{})
- func Debugf(msg string, a ...interface{})
- func Debugln(a ...interface{})
- func Emergency(msg interface{})
- func EmergencyFatal(msg interface{})
- func EmergencyPanic(msg interface{})
- func EmergencyWhen(conditional bool, m interface{})
- func Emergencyf(msg string, a ...interface{})
- func Emergencyln(a ...interface{})
- func Error(msg interface{})
- func ErrorTimeFinder(err error) (time.Time, bool)
- func ErrorWhen(conditional bool, m 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 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 Logf(l level.Priority, msg string, a ...interface{})
- func Logln(l level.Priority, a ...interface{})
- func MakeCatcherErrorHandler(catcher Catcher, fallback send.Sender) send.ErrorHandler
- func MakeStandardLogger(p level.Priority) *log.Logger
- func Name() string
- func Notice(msg interface{})
- func NoticeWhen(conditional bool, m interface{})
- func Noticef(msg string, a ...interface{})
- func Noticeln(a ...interface{})
- func SetDefaultJournaler(l Journaler)
- func SetDefaultStandardLogger(p level.Priority)
- func SetLevel(info send.LevelInfo) error
- func SetName(name string)
- func SetSender(s send.Sender) error
- func Warning(msg interface{})
- func WarningWhen(conditional bool, m interface{})
- func Warningf(msg string, a ...interface{})
- func Warningln(a ...interface{})
- func WrapErrorTime(err error) error
- func WrapErrorTimeMessage(err error, m string) error
- func WrapErrorTimeMessagef(err error, m string, args ...interface{}) error
- type Catcher
- func MakeBasicCatcher(size int) Catcher
- func MakeExtendedCatcher(size int) Catcher
- func MakeExtendedTimestampCatcher(size int) Catcher
- func MakeSimpleCatcher(size int) Catcher
- func MakeTimestampCatcher(size int) Catcher
- func NewBasicCatcher() Catcher
- func NewCatcher() Catcher
- func NewExtendedCatcher() Catcher
- func NewExtendedTimestampCatcher() Catcher
- func NewSimpleCatcher() Catcher
- func NewTimestampCatcher() Catcher
- type CheckFunction
- type Journaler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CriticalWhen ¶
func CriticalWhen(conditional bool, m interface{})
func Criticalln ¶
func Criticalln(a ...interface{})
func EmergencyFatal ¶
func EmergencyFatal(msg interface{})
func EmergencyPanic ¶
func EmergencyPanic(msg interface{})
func EmergencyWhen ¶
func EmergencyWhen(conditional bool, m interface{})
func Emergencyf ¶
func Emergencyf(msg string, a ...interface{})
func Emergencyln ¶
func Emergencyln(a ...interface{})
func ErrorTimeFinder ¶
ErrorTimeFinder unwraps a timestamp annotated error if possible and is capable of finding a timestamp in an error that has been annotated using pkg/errors.
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 MakeCatcherErrorHandler ¶
func MakeCatcherErrorHandler(catcher Catcher, fallback send.Sender) send.ErrorHandler
MakeCatcherErrorHandler produces an error handler useful for collecting errors from a sender using the supplied error catcher. At the very least, consider using a catcher that has a specified maxsize, and possibly timestamp annotating catcher as well. If you
func MakeStandardLogger ¶
MakeStandardLogger constructs a standard library logging instance that logs all messages to the global grip logging instance.
func NoticeWhen ¶
func NoticeWhen(conditional bool, m interface{})
func SetDefaultJournaler ¶
func SetDefaultJournaler(l Journaler)
SetDefaultJournaler allows you to override the standard logger, that is used by calls in the grip package. This call is not thread safe relative to other logging calls, or the GetDefaultJournaler call, although all journaling methods are safe: as a result be sure to only call this method during package and process initialization.
func SetDefaultStandardLogger ¶
SetDefaultStandardLogger set's the standard library's global logging instance to use grip's global logger at the specified level.
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 WrapErrorTime ¶
WrapErrorTime annotates an error with the timestamp. The underlying concrete object implements message.Composer as well as error.
func WrapErrorTimeMessage ¶
WrapErrorTimeMessage annotates an error with the timestamp and a string form. The underlying concrete object implements message.Composer as well as error.
func WrapErrorTimeMessagef ¶
WrapErrorTimeMessagef annotates an error with a timestamp and a string formated message, like fmt.Sprintf or fmt.Errorf. The underlying concrete object implements message.Composer as well as error.
Types ¶
type Catcher ¶
type Catcher interface {
Add(error)
AddWhen(bool, error)
Extend([]error)
ExtendWhen(bool, []error)
Len() int
HasErrors() bool
String() string
Resolve() error
Errors() []error
New(string)
NewWhen(bool, string)
Errorf(string, ...interface{})
ErrorfWhen(bool, string, ...interface{})
Wrap(error, string)
Wrapf(error, string, ...interface{})
Check(CheckFunction)
CheckExtend([]CheckFunction)
CheckWhen(bool, CheckFunction)
}
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 MakeBasicCatcher ¶
MakeBasicCatcher collects error messages and formats them using a new-line separated string of the output of error.Error(). If the size greater than 0 the catcher will never collect more than the specified number of errors, discarding earlier messages when adding new messages.
func MakeExtendedCatcher ¶
MakeExtendedCatcher collects error messages and formats them using a new-line separated string of the extended string format of the error message (e.g. %+v). If the size greater than 0 the catcher will never collect more than the specified number of errors, discarding earlier messages when adding new messages.
func MakeExtendedTimestampCatcher ¶
MakeTimestampCatcher constructs a Catcher instance that annotates all errors with their collection time and also captures stacks when possible. If the size greater than 0 the catcher will never collect more than the specified number of errors, discarding earlier messages when adding new messages.
func MakeSimpleCatcher ¶
MakeSimpleCatcher collects error messages and formats them using a new-line separated string of the string format of the error message (e.g. %s). If the size greater than 0 the catcher will never collect more than the specified number of errors, discarding earlier messages when adding new messages.
func MakeTimestampCatcher ¶
MakeTimestampCatcher constructs a Catcher instance that annotates all errors with their collection time; however, if the size is greater than 0 the catcher will never collect more than the specified number of errors, discarding earlier messages when adding new messages.
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 NewExtendedTimestampCatcher ¶
func NewExtendedTimestampCatcher() Catcher
NewExtendedTimestampCatcher adds long-form annotation to the aggregated error message (e.g. including stacks, when possible.)
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).
func NewTimestampCatcher ¶
func NewTimestampCatcher() Catcher
NewTimestampCatcher produces a Catcher instance that reports the short form of all constituent errors and annotates those errors with a timestamp to reflect when the error was collected.
type CheckFunction ¶
type CheckFunction func() error
CheckFunction are functions which take no arguments and return an error.
type Journaler ¶
type Journaler interface {
Name() string
SetName(string)
// Methods to access the underlying message sending backend.
GetSender() send.Sender
SetSender(send.Sender) error
SetLevel(send.LevelInfo) error
// Send allows you to push a composer which stores its own
// priorty (or uses the sender's default priority).
Send(interface{})
// 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{})
// 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.
EmergencyFatal(interface{})
EmergencyPanic(interface{})
// For each level, in addition to a basic logger that takes
// strings and message.Composer objects (and tries to do its best
// with everythingelse.) there are println and printf
// loggers. Each Level also has "When" variants that only log
// if the passed condition are true.
Emergency(interface{})
Emergencyf(string, ...interface{})
Emergencyln(...interface{})
EmergencyWhen(bool, interface{})
Alert(interface{})
Alertf(string, ...interface{})
Alertln(...interface{})
AlertWhen(bool, interface{})
Critical(interface{})
Criticalf(string, ...interface{})
Criticalln(...interface{})
CriticalWhen(bool, interface{})
Error(interface{})
Errorf(string, ...interface{})
Errorln(...interface{})
ErrorWhen(bool, interface{})
Warning(interface{})
Warningf(string, ...interface{})
Warningln(...interface{})
WarningWhen(bool, interface{})
Notice(interface{})
Noticef(string, ...interface{})
Noticeln(...interface{})
NoticeWhen(bool, interface{})
Info(interface{})
Infof(string, ...interface{})
Infoln(...interface{})
InfoWhen(bool, interface{})
Debug(interface{})
Debugf(string, ...interface{})
Debugln(...interface{})
DebugWhen(bool, interface{})
}
Journaler describes the public interface of the the Grip interface. Used to enforce consistency between the grip and logging packages.
func GetDefaultJournaler ¶
func GetDefaultJournaler() Journaler
GetDefaultJournaler returns the default journal instance used by this library. This call is not thread safe relative to other logging calls, or SetDefaultJournaler call, although all journaling methods are safe.
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 |
|---|---|
|
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. |