docs.go

// 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.
//
// The `/x` packages contain implementations of send.Sender that have
// additional dependencies and mostly deliver messages to targets
// including external logging aggregators (e.g. splunk) or other
// interesting targets (e.g. slack, email, jira issues, github
// comments, etc.) which may be useful when building different kinds
// of services.
//
// 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.Composer 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 `f` or `ln` appended to
// the end of the method name which allow Printf() and Println() style
// functionality. You must pass printf-style arguments to the `f`
// methods.
//
// Conditional Logging
//
// The Conditional ("When") logging methods take two arguments, a
// Boolean, and a message argument. Messages can be strings, objects that
// implement the message.Composer 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 Composers to avoid expensive
// message building operations.
package grip

// This file is intentionally documentation only.