Documentation
¶
Overview ¶
Package logging implements attribute-based logging. Log entries consist of timestamps, an actor and event string, and a mapping of string key-value attribute pairs. For example,
log.Error("serialiser", "failed to open file",
map[string]string{
"error": err.Error(),
"path": "data.bin",
})
This produces the output message
[2016-04-01T15:04:30-0700] [ERROR] [actor:serialiser event:failed to open file] error=is a directory path=data.bin
Example ¶
package main
import (
"time"
"git.wntrmute.dev/kyle/goutils/logging"
)
var log = logging.NewConsole()
var olog = logging.NewConsole()
func main() {
log.Info("example", "Hello, world.", nil)
log.Warn("example", "this program is about to end", nil)
log.Critical("example", "screaming into the void", nil)
olog.Critical("other", "can anyone hear me?", nil)
log.Warn("example", "but not for long", nil)
log.Info("example", "fare thee well", nil)
olog.Info("example", "all good journeys must come to an end",
map[string]string{"when": time.Now().String()})
}
Output:
Index ¶
- Constants
- type Console
- type File
- type Level
- type LogWriter
- func (lw *LogWriter) Close() error
- func (lw *LogWriter) Critical(actor, event string, attrs map[string]string)
- func (lw *LogWriter) Debug(actor, event string, attrs map[string]string)
- func (lw *LogWriter) Error(actor, event string, attrs map[string]string)
- func (lw *LogWriter) Fatal(actor, event string, attrs map[string]string)
- func (lw *LogWriter) FatalCode(exitcode int, actor, event string, attrs map[string]string)
- func (lw *LogWriter) FatalNoDie(actor, event string, attrs map[string]string)
- func (lw *LogWriter) Good() bool
- func (lw *LogWriter) Info(actor, event string, attrs map[string]string)
- func (lw *LogWriter) SetLevel(l Level)
- func (lw *LogWriter) Status() error
- func (lw *LogWriter) Warn(actor, event string, attrs map[string]string)
- type Logger
- type Multi
- func (m *Multi) Close() error
- func (m *Multi) Critical(actor, event string, attrs map[string]string)
- func (m *Multi) Debug(actor, event string, attrs map[string]string)
- func (m *Multi) Error(actor, event string, attrs map[string]string)
- func (m *Multi) Fatal(actor, event string, attrs map[string]string)
- func (m *Multi) FatalCode(exitcode int, actor, event string, attrs map[string]string)
- func (m *Multi) FatalNoDie(actor, event string, attrs map[string]string)
- func (m *Multi) Good() bool
- func (m *Multi) Info(actor, event string, attrs map[string]string)
- func (m *Multi) SetLevel(level Level)
- func (m *Multi) Status() error
- func (m *Multi) Warn(actor, event string, attrs map[string]string)
Examples ¶
Constants ¶
const ( // LevelDebug are debug output useful during program testing // and debugging. LevelDebug = 1 << iota // LevelInfo is used for informational messages. LevelInfo // LevelWarning is for messages that are warning conditions: // they're not indicative of a failure, but of a situation // that may lead to a failure later. LevelWarning // LevelError is for messages indicating an error of some // kind. LevelError // LevelCritical are messages for critical conditions. LevelCritical // LevelFatal messages are akin to syslog's LOG_EMERG: the // system is unusable and cannot continue execution. LevelFatal )
The following constants represent logging levels in increasing levels of seriousness.
const DateFormat = "2006-01-02T15:03:04-0700"
DateFormat contains the default date format string used by the logger.
const DefaultLevel = LevelInfo
DefaultLevel is the default logging level when none is provided.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Console ¶
type Console struct {
*LogWriter
}
Console is a Logger that writes to the console. It must be constructed with a call to NewConsole.
type File ¶
type File struct {
*LogWriter
// contains filtered or unexported fields
}
File writes its logs to file.
func NewFile ¶
NewFile creates a new Logger that writes all logs to the file specified by path. If overwrite is specified, the log file will be truncated before writing. Otherwise, the log file will be appended to.
func NewSplitFile ¶
NewSplitFile creates a new Logger that writes debug and information messages to the output file, and warning and higher messages to the error file. If overwrite is specified, the log files will be truncated before writing.
type LogWriter ¶
type LogWriter struct {
// contains filtered or unexported fields
}
A LogWriter is a Logger that operates on an io.Writer.
func NewLogWriter ¶
NewLogWriter takes an output writer (wo) and an error writer (we), and produces a new Logger. If the error writer is nil, error logs will be multiplexed onto the output writer.
func (*LogWriter) Critical ¶
Critical emits a message indicating a critical condition. The error, if uncorrected, is likely to cause a fatal condition shortly. An example is running out of disk space. This is something that the ops team should get paged for.
Actor specifies the component emitting the message; event indicates the event that caused the log message to be emitted. attrs is a map of key-value string pairs that can be used to provide additional information.
func (*LogWriter) Debug ¶
Debug emits a debug-level message. These are only used during development or if a deployed system repeatedly sees abnormal errors.
Actor specifies the component emitting the message; event indicates the event that caused the log message to be emitted. attrs is a map of key-value string pairs that can be used to provide additional information.
func (*LogWriter) Error ¶
Error emits an error message. A single error doesn't require an ops team to be paged, but repeated errors should often trigger a page based on threshold triggers. An example is a network failure: it might be a transient failure (these do happen), but most of the time it's self-correcting.
Actor specifies the component emitting the message; event indicates the event that caused the log message to be emitted. attrs is a map of key-value string pairs that can be used to provide additional information.
func (*LogWriter) Fatal ¶
Fatal emits a message indicating that the system is in an unsuable state, and cannot continue to run. The program will exit with exit code 1.
Actor specifies the component emitting the message; event indicates the event that caused the log message to be emitted. attrs is a map of key-value string pairs that can be used to provide additional information.
func (*LogWriter) FatalCode ¶
FatalCode emits a message indicating that the system is in an unsuable state, and cannot continue to run. The program will exit with the exit code speicfied in the exitcode argument.
Actor specifies the component emitting the message; event indicates the event that caused the log message to be emitted. attrs is a map of key-value string pairs that can be used to provide additional information.
func (*LogWriter) FatalNoDie ¶
FatalNoDie emits a message indicating that the system is in an unsuable state, and cannot continue to run. The program will not exit; it is assumed that the caller has some final clean up to perform.
Actor specifies the component emitting the message; event indicates the event that caused the log message to be emitted. attrs is a map of key-value string pairs that can be used to provide additional information.
func (*LogWriter) Info ¶
Info emits an informational message. This is a normal log message that is used to deliver information, such as recording requests. Ops teams are never paged for informational messages. This is the default log level.
Actor specifies the component emitting the message; event indicates the event that caused the log message to be emitted. attrs is a map of key-value string pairs that can be used to provide additional information.
func (*LogWriter) Status ¶
Status returns an error value from the logger if it isn't healthy, or nil if the logger is healthy.
func (*LogWriter) Warn ¶
Warn emits a warning message. An example of this is a bad request sent to a server. This isn't an error on the part of the program, but it may be indicative of other things. Like errors, the ops team shouldn't be paged for errors, but a page might be triggered if a certain threshold of warnings is reached (which is typically much higher than errors). For example, repeated warnings might be a sign that the system is under attack.
Actor specifies the component emitting the message; event indicates the event that caused the log message to be emitted. attrs is a map of key-value string pairs that can be used to provide additional information.
type Logger ¶
type Logger interface {
// SetLevel sets the minimum log level.
SetLevel(Level)
// Good returns true if the Logger is healthy.
Good() bool
// Status returns an error corresponding to the logger's state;
// if it's healthy (e.g. Good() returns true), Error will
// return nil.
Status() error
// Close gives the Logger the opportunity to perform any cleanup.
Close() error
Debug(actor, event string, attrs map[string]string)
Info(actor, event string, attrs map[string]string)
Warn(actor, event string, attrs map[string]string)
Error(actor, event string, attrs map[string]string)
Critical(actor, event string, attrs map[string]string)
Fatal(actor, event string, attrs map[string]string)
FatalCode(exitcode int, actor, event string, attrs map[string]string)
FatalNoDie(actor, event string, attrs map[string]string)
}
Logger provides a standardised logging interface.
Log messages consist of four components:
The **level** attaches a notion of priority to the log message. Several log levels are available:
+ FATAL (32): the system is in an unsuable state, and cannot continue to run. Most of the logging for this will cause the program to exit with an error code. + CRITICAL (16): critical conditions. The error, if uncorrected, is likely to cause a fatal condition shortly. An example is running out of disk space. This is something that the ops team should get paged for. + ERROR (8): error conditions. A single error doesn't require an ops team to be paged, but repeated errors should often trigger a page based on threshold triggers. An example is a network failure: it might be a transient failure (these do happen), but most of the time it's self-correcting. + WARNING (4): warning conditions. An example of this is a bad request sent to a server. This isn't an error on the part of the program, but it may be indicative of other things. Like errors, the ops team shouldn't be paged for errors, but a page might be triggered if a certain threshold of warnings is reached (which is typically much higher than errors). For example, repeated warnings might be a sign that the system is under attack. + INFO (2): informational message. This is a normal log message that is used to deliver information, such as recording requests. Ops teams are never paged for informational messages. This is the default log level. + DEBUG (1): debug-level message. These are only used during development or if a deployed system repeatedly sees abnormal errors.
The numeric values indicate the priority of a given level.
- The **actor** is used to specify which component is generating the log message. This could be the program name, or it could be a specific component inside the system.
- The **event** is a short message indicating what happened. This is most like the traditional log message.
- The **attributes** are an optional set of key-value string pairs that provide additional information.
Additionally, each log message has an associated timestamp. For the text-based logs, this is "%FT%T%z"; for the binary logs, this is a 64-bit Unix timestamp. An example text-based timestamp might look like ::
[2016-03-27T20:59:27-0700] [INFO] [actor:server event:request received] client=192.168.2.5 request-size=839
Note that this is organised in a manner that facilitates parsing::
/\[(\d{4}-\d{3}-\d{2}T\d{2}:\d{2}:\d{2}[+-]\d{4})\] \[(\w+\)]\) \[actor:(.+?) event:(.+?)\]/
will cover the header:
+ “$1“ contains the timestamp + “$2“ contains the level + “$3“ contains the actor + “$4“ contains the event
type Multi ¶ added in v1.6.0
type Multi struct {
// contains filtered or unexported fields
}
Multi allows combining of loggers.
Source Files
Directories