README
¶
gologme/log
This package is a drop in replacement for the built-in Go log package. All the functionality of the built-in package still exists and is unchanged. In addition, this package contains a series of small enhancements and additions. Namely, it adds four logging levels. These logging levels are:
- Error
- Warn
- Info
- Debug
- Trace
In addition to these four defined logging levels, users can also define their own arbitrary logging levels.
Unlike other loggers, these logging levels are not enabled in a chain. Meaning, once a level is enabled, say Warn, all levels above it are not also enabled. This package is implemented in such a way that users can individually turn on and turn off the various new logging levels. If existing code uses the build-in log package, no change is needed to use this package.
Another feature that was added, based on comments seen on the various golang boards, is the ability to set the calldepth.
Version
1.3.0
New to version 1.3.0
- Made changes to bring it current as of Go 1.17.1 so it remains a drop in replacement
- Made chagnes based on feedback
- Sorted log levels into natural order
- Enabled formatted prefixes that include the log level (e.g., [info] {rest of log line})
Installation
This package can be installed with the go get command:
go get github.com/gologme/log
go install github.com/gologme/log
Example
Just like the built-in package, code can still do simple logging just like:
log.Println("some interesting logging message")
In addition to this, users can enable info, warn, error, debug, or trace logging like:
log.EnableLevel("error")
log.EnableLevel("warn")
log.EnableLevel("info")
log.EnableLevel("debug")
log.EnableLevel("trace")
Once these levels are enabled, calls to the info, warn, error, debug, or trace loggers will print out just like they do for the Print and Fatal built-in loggers. The functions / methods definitions that are defined for each level, match exactly the ones defined in the built-in package. The new functions/methods are called:
log.Error()
log.Errorf()
log.Errorln()
log.Warn()
log.Warnf()
log.Warnln()
log.Info()
log.Infof()
log.Infoln()
log.Debug()
log.Debugf()
log.Debugln()
log.Trace()
log.Tracef()
log.Traceln()
In addition to the defined levels, arbitrary levels can be enabled. For example:
log.EnableLevel("tracedebug")
This level can then be used from an application as shown below. All three functions/methods are defined for this: log.Level(), log.Levelln(), log.Levelf(). For each of these, the first argument is the level name.
log.Levelln("tracedebug", "some other neat logging message for this level")
To enable the log level to be included in the prefix enable it.
log.EnableFormattedPrefix()
This will make the log lines look like, note the log level prefix:
[debug] 2021/10/15 12:46:52 some logging message
To enable logging by the following numerical levels Level 10 = panic, fatal, error, warn, info, debug, & trace Level 5 = panic, fatal, error, warn, info, & debug Level 4 = panic, fatal, error, warn, & info Level 3 = panic, fatal, error, & warn Level 2 = panic, fatal & error Level 1 = panic, fatal
log.EnableLevelsByNumber(int)
To disable all logging levels
log.DisableAllLevels()
The last thing that was enabled was the ability to define the calldepth. The built-in package from the Go authors had this hard coded to a value of 2. A small change was made to enable this to be set by the application using the log package. From the Go authors source code it seems like the normal possible values would be 1, 2, or 3.
log.SetCallDepth(int)
License
This is free software, licensed under the same BSD license that the original Go log package was licensed.
Copyright
Copyright 2017 Bret Jordan, All rights reserved.
Documentation
¶
Overview ¶
Package log implements a simple logging package. It defines a type, Logger, with methods for formatting output. It also has a predefined 'standard' Logger accessible through helper functions Print[f|ln], Fatal[f|ln], and Panic[f|ln], which are easier to use than creating a Logger manually. That logger writes to standard error and prints the date and time of each logged message. Every log message is output on a separate line: if the message being printed does not end in a newline, the logger will add one. The Fatal functions call os.Exit(1) after writing the log message. The Panic functions call panic after writing the log message.
Index ¶
- Constants
- func Debug(v ...interface{})
- func Debugf(format string, v ...interface{})
- func Debugln(v ...interface{})
- func DisableAllLevels()
- func DisableLevel(level string)
- func EnableFormattedPrefix()
- func EnableLevel(level string)
- func EnableLevelsByNumber(num int)
- func Error(v ...interface{})
- func Errorf(format string, v ...interface{})
- func Errorln(v ...interface{})
- func Fatal(v ...interface{})
- func Fatalf(format string, v ...interface{})
- func Fatalln(v ...interface{})
- func Flags() int
- func GetLevel(level string) bool
- func Info(v ...interface{})
- func Infof(format string, v ...interface{})
- func Infoln(v ...interface{})
- func Level(level string, v ...interface{})
- func Levelf(level, format string, v ...interface{})
- func Levelln(level string, v ...interface{})
- func Output(level string, s string) error
- func Panic(v ...interface{})
- func Panicf(format string, v ...interface{})
- func Panicln(v ...interface{})
- func Prefix() string
- func Print(v ...interface{})
- func Printf(format string, v ...interface{})
- func Println(v ...interface{})
- func SetCallDepth(d int)
- func SetFlags(flag int)
- func SetOutput(w io.Writer)
- func SetPrefix(prefix string)
- func Trace(v ...interface{})
- func Tracef(format string, v ...interface{})
- func Traceln(v ...interface{})
- func Warn(v ...interface{})
- func Warnf(format string, v ...interface{})
- func Warnln(v ...interface{})
- func Writer() io.Writer
- type Logger
- func (l *Logger) Debug(v ...interface{})
- func (l *Logger) Debugf(format string, v ...interface{})
- func (l *Logger) Debugln(v ...interface{})
- func (l *Logger) DisableAllLevels()
- func (l *Logger) DisableLevel(level string)
- func (l *Logger) EnableFormattedPrefix()
- func (l *Logger) EnableLevel(level string)
- func (l *Logger) EnableLevelsByNumber(num int)
- func (l *Logger) Error(v ...interface{})
- func (l *Logger) Errorf(format string, v ...interface{})
- func (l *Logger) Errorln(v ...interface{})
- func (l *Logger) Fatal(v ...interface{})
- func (l *Logger) Fatalf(format string, v ...interface{})
- func (l *Logger) Fatalln(v ...interface{})
- func (l *Logger) Flags() int
- func (l *Logger) GetLevel(level string) bool
- func (l *Logger) Info(v ...interface{})
- func (l *Logger) Infof(format string, v ...interface{})
- func (l *Logger) Infoln(v ...interface{})
- func (l *Logger) Level(level string, v ...interface{})
- func (l *Logger) Levelf(level, format string, v ...interface{})
- func (l *Logger) Levelln(level string, v ...interface{})
- func (l *Logger) Output(level string, s string) error
- func (l *Logger) Panic(v ...interface{})
- func (l *Logger) Panicf(format string, v ...interface{})
- func (l *Logger) Panicln(v ...interface{})
- func (l *Logger) Prefix() string
- func (l *Logger) Print(v ...interface{})
- func (l *Logger) Printf(format string, v ...interface{})
- func (l *Logger) Println(v ...interface{})
- func (l *Logger) SetCallDepth(d int)
- func (l *Logger) SetFlags(flag int)
- func (l *Logger) SetOutput(w io.Writer)
- func (l *Logger) SetPrefix(prefix string)
- func (l *Logger) Trace(v ...interface{})
- func (l *Logger) Tracef(format string, v ...interface{})
- func (l *Logger) Traceln(v ...interface{})
- func (l *Logger) Warn(v ...interface{})
- func (l *Logger) Warnf(format string, v ...interface{})
- func (l *Logger) Warnln(v ...interface{})
- func (l *Logger) Writer() io.Writer
Constants ¶
const ( Ldate = 1 << iota // the date in the local time zone: 2009/01/23 Ltime // the time in the local time zone: 01:23:23 Lmicroseconds // microsecond resolution: 01:23:23.123123. assumes Ltime. Llongfile // full file name and line number: /a/b/c/d.go:23 Lshortfile // final file name element and line number: d.go:23. overrides Llongfile LUTC // if Ldate or Ltime is set, use UTC rather than the local time zone Lmsgprefix // move the "prefix" from the beginning of the line to before the message LstdFlags = Ldate | Ltime // initial values for the standard logger )
These flags define which text to prefix to each log entry generated by the Logger. Bits are or'ed together to control what's printed. With the exception of the Lmsgprefix flag, there is no control over the order they appear (the order listed here) or the format they present (as described in the comments). The prefix is followed by a colon only when Llongfile or Lshortfile is specified. For example, flags Ldate | Ltime (or LstdFlags) produce,
2009/01/23 01:23:23 message
while flags Ldate | Ltime | Lmicroseconds | Llongfile produce,
2009/01/23 01:23:23.123123 /a/b/c/d.go:23: message
Variables ¶
This section is empty.
Functions ¶
func Debug ¶
func Debug(v ...interface{})
Debug - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func Debugf ¶
func Debugf(format string, v ...interface{})
Debugf - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func Debugln ¶
func Debugln(v ...interface{})
Debugln - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func DisableAllLevels ¶
func DisableAllLevels()
DisableAllLevels - This function will the output from all logging level
func DisableLevel ¶
func DisableLevel(level string)
DisableLevel - This function will disable the output from the supplied logging level
func EnableFormattedPrefix ¶
func EnableFormattedPrefix()
EnableFormattedPrefix - This function will enable the formatted prefix in output
func EnableLevel ¶
func EnableLevel(level string)
EnableLevel - This function will enable the output from the supplied logging level
func EnableLevelsByNumber ¶
func EnableLevelsByNumber(num int)
EnableLevelsByNumber - This function will enable logging levels by number
func Error ¶
func Error(v ...interface{})
Error - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func Errorf ¶
func Errorf(format string, v ...interface{})
Errorf - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func Errorln ¶
func Errorln(v ...interface{})
Errorln - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func Fatal ¶
func Fatal(v ...interface{})
Fatal is equivalent to Print() followed by a call to os.Exit(1). Jordan: added fatal as a level so it can show up in formatted logs
func Fatalf ¶
func Fatalf(format string, v ...interface{})
Fatalf is equivalent to Printf() followed by a call to os.Exit(1). Jordan: added fatal as a level so it can show up in formatted logs
func Fatalln ¶
func Fatalln(v ...interface{})
Fatalln is equivalent to Println() followed by a call to os.Exit(1). Jordan: added fatal as a level so it can show up in formatted logs
func Flags ¶
func Flags() int
Flags returns the output flags for the standard logger. The flag bits are Ldate, Ltime, and so on.
func Info ¶
func Info(v ...interface{})
Info - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func Infof ¶
func Infof(format string, v ...interface{})
Infof - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func Infoln ¶
func Infoln(v ...interface{})
Infoln - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func Level ¶
func Level(level string, v ...interface{})
Level - This function calls Output to print to the standard logger. The first parameter is a logging level, this allows the printing of arbitrary logging levels. Arguments are handled in the manner of fmt.Print.
func Levelf ¶
func Levelf(level, format string, v ...interface{})
Levelf - This function calls Output to print to the standard logger. The first parameter is a logging level, this allows the printing of arbitrary logging levels. Arguments are handled in the manner of fmt.Printf.
func Levelln ¶
func Levelln(level string, v ...interface{})
Levelln - This function calls Output to print to the standard logger. The first parameter is a logging level, this allows the printing of arbitrary logging levels. Arguments are handled in the manner of fmt.Println.
func Output ¶
Output writes the output for a logging event. The string s contains the text to print after the prefix specified by the flags of the Logger. A newline is appended if the last character of s is not already a newline. Calldepth is the count of the number of frames to skip when computing the file name and line number if Llongfile or Lshortfile is set; a value of 1 will print the details for the caller of Output. Jordan: calldepth is set on the object so passing in empty levels
func Panic ¶
func Panic(v ...interface{})
Panic is equivalent to Print() followed by a call to panic(). Jordan: added panic as a level so it can show up in formatted logs
func Panicf ¶
func Panicf(format string, v ...interface{})
Panicf is equivalent to Printf() followed by a call to panic(). Jordan: added panic as a level so it can show up in formatted logs
func Panicln ¶
func Panicln(v ...interface{})
Panicln is equivalent to Println() followed by a call to panic(). Jordan: added panic as a level so it can show up in formatted logs
func Print ¶
func Print(v ...interface{})
Print calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func Printf ¶
func Printf(format string, v ...interface{})
Printf calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func Println ¶
func Println(v ...interface{})
Println calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func SetCallDepth ¶
func SetCallDepth(d int)
SetCallDepth - This function will set the call depth. By default the call depth is set at 2. A depth of 2 represents the behavior of the standard library.
func SetFlags ¶
func SetFlags(flag int)
SetFlags sets the output flags for the standard logger. The flag bits are Ldate, Ltime, and so on.
func SetPrefix ¶
func SetPrefix(prefix string)
SetPrefix sets the output prefix for the standard logger.
func Trace ¶
func Trace(v ...interface{})
Trace - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func Tracef ¶
func Tracef(format string, v ...interface{})
Tracef - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func Traceln ¶
func Traceln(v ...interface{})
Traceln - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func Warn ¶
func Warn(v ...interface{})
Warn - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func Warnf ¶
func Warnf(format string, v ...interface{})
Warnf - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
Types ¶
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
A Logger represents an active logging object that generates lines of output to an io.Writer. Each logging operation makes a single call to the Writer's Write method. A Logger can be used simultaneously from multiple goroutines; it guarantees to serialize access to the Writer.
Calldepth is used to recover the PC and is provided for generality, although at the moment on all pre-defined paths it will be 2. Jordan: Added calldepth, levels, and formattedPrefix to the struct
func Default ¶
func Default() *Logger
Default returns the standard logger used by the package-level output functions.
func New ¶
New creates a new Logger. The out variable sets the destination to which log data will be written. The prefix appears at the beginning of each generated log line, or after the log header if the Lmsgprefix flag is provided. The flag argument defines the logging properties. Jordan: Added levels and enabled fatal by default
func (*Logger) Debug ¶
func (l *Logger) Debug(v ...interface{})
Debug - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func (*Logger) Debugf ¶
Debugf - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func (*Logger) Debugln ¶
func (l *Logger) Debugln(v ...interface{})
Debugln - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func (*Logger) DisableAllLevels ¶
func (l *Logger) DisableAllLevels()
DisableAllLevels - This function will the output from all logging level
func (*Logger) DisableLevel ¶
DisableLevel - This function will disable the output from the supplied logging level
func (*Logger) EnableFormattedPrefix ¶
func (l *Logger) EnableFormattedPrefix()
EnableFormattedPrefix - This function will enable the formatted prefix in output
func (*Logger) EnableLevel ¶
EnableLevel - This function will enable the output from the supplied logging level
func (*Logger) EnableLevelsByNumber ¶
EnableLevelsByNumber - This function will enable logging levels by number
func (*Logger) Error ¶
func (l *Logger) Error(v ...interface{})
Error - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func (*Logger) Errorf ¶
Errorf - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func (*Logger) Errorln ¶
func (l *Logger) Errorln(v ...interface{})
Errorln - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func (*Logger) Fatal ¶
func (l *Logger) Fatal(v ...interface{})
Fatal is equivalent to l.Print() followed by a call to os.Exit(1). Jordan: added fatal as a level so it can show up in formatted logs
func (*Logger) Fatalf ¶
Fatalf is equivalent to l.Printf() followed by a call to os.Exit(1). Jordan: added fatal as a level so it can show up in formatted logs
func (*Logger) Fatalln ¶
func (l *Logger) Fatalln(v ...interface{})
Fatalln is equivalent to l.Println() followed by a call to os.Exit(1). Jordan: added fatal as a level so it can show up in formatted logs
func (*Logger) Flags ¶
Flags returns the output flags for the logger. The flag bits are Ldate, Ltime, and so on.
func (*Logger) Info ¶
func (l *Logger) Info(v ...interface{})
Info - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func (*Logger) Infof ¶
Infof - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func (*Logger) Infoln ¶
func (l *Logger) Infoln(v ...interface{})
Infoln - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func (*Logger) Level ¶
Level - This function calls Output to print to the standard logger. The first parameter is a logging level, this allows the printing of arbitrary logging levels. Arguments are handled in the manner of fmt.Print.
func (*Logger) Levelf ¶
Levelf - This function calls Output to print to the standard logger. The first parameter is a logging level, this allows the printing of arbitrary logging levels. Arguments are handled in the manner of fmt.Printf.
func (*Logger) Levelln ¶
Levelln - This function calls Output to print to the standard logger. The first parameter is a logging level, this allows the printing of arbitrary logging levels. Arguments are handled in the manner of fmt.Println.
func (*Logger) Output ¶
Output writes the output for a logging event. The string s contains the text to print after the prefix specified by the flags of the Logger. A newline is appended if the last character of s is not already a newline. Calldepth is used to recover the PC and is provided for generality, although at the moment on all pre-defined paths it will be 2. Jordan: Set calldepth and allow default levels. Call depth is now in object
func (*Logger) Panic ¶
func (l *Logger) Panic(v ...interface{})
Panic is equivalent to l.Print() followed by a call to panic(). Jordan: added panic as a level so it can show up in formatted logs
func (*Logger) Panicf ¶
Panicf is equivalent to l.Printf() followed by a call to panic(). Jordan: added panic as a level so it can show up in formatted logs
func (*Logger) Panicln ¶
func (l *Logger) Panicln(v ...interface{})
Panicln is equivalent to l.Println() followed by a call to panic(). Jordan: added panic as a level so it can show up in formatted logs
func (*Logger) Print ¶
func (l *Logger) Print(v ...interface{})
Print calls l.Output to print to the logger. Arguments are handled in the manner of fmt.Print.
func (*Logger) Printf ¶
Printf calls l.Output to print to the logger. Arguments are handled in the manner of fmt.Printf.
func (*Logger) Println ¶
func (l *Logger) Println(v ...interface{})
Println calls l.Output to print to the logger. Arguments are handled in the manner of fmt.Println.
func (*Logger) SetCallDepth ¶
SetCallDepth - This function will set the call depth. By default the call depth is set at 2. A depth of 2 represents the behavior of the standard library.
func (*Logger) SetFlags ¶
SetFlags sets the output flags for the logger. The flag bits are Ldate, Ltime, and so on.
func (*Logger) Trace ¶
func (l *Logger) Trace(v ...interface{})
Trace - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func (*Logger) Tracef ¶
Tracef - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
func (*Logger) Traceln ¶
func (l *Logger) Traceln(v ...interface{})
Traceln - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Println.
func (*Logger) Warn ¶
func (l *Logger) Warn(v ...interface{})
Warn - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Print.
func (*Logger) Warnf ¶
Warnf - This function calls Output to print to the standard logger. Arguments are handled in the manner of fmt.Printf.
Source Files