Documentation ¶
Overview ¶
Package log4go provides level-based and highly configurable logging.
Enhanced Logging ¶
This is inspired by the logging functionality in Java. Essentially, you create a Logger object and create output filters for it. You can send whatever you want to the Logger, and it will filter that based on your settings and send it to the outputs. This way, you can put as much debug code in your program as you want, and when you're done you can filter out the mundane messages so only the important ones show up.
Utility functions are provided to make life easier. Here is some example code to get started:
log := log4go.NewLogger() log.AddFilter("stdout", log4go.DEBUG, log4go.NewConsoleLogWriter()) log.AddFilter("log", log4go.FINE, log4go.NewFileLogWriter("example.log", true)) log.Info("The time is now: %s", time.LocalTime().Format("15:04:05 MST 2006/01/02"))
The first two lines can be combined with the utility NewDefaultLogger:
log := log4go.NewDefaultLogger(log4go.DEBUG) log.AddFilter("log", log4go.FINE, log4go.NewFileLogWriter("example.log", true)) log.Info("The time is now: %s", time.LocalTime().Format("15:04:05 MST 2006/01/02"))
Usage notes:
- The ConsoleLogWriter does not display the source of the message to standard output, but the FileLogWriter does.
- The utility functions (Info, Debug, Warn, etc) derive their source from the calling function, and this incurs extra overhead.
Changes from 2.0:
- The external interface has remained mostly stable, but a lot of the internals have been changed, so if you depended on any of this or created your own LogWriter, then you will probably have to update your code. In particular, Logger is now a map and ConsoleLogWriter is now a channel behind-the-scenes, and the LogWrite method no longer has return values.
Future work: (please let me know if you think I should work on any of these particularly)
- Log file rotation
- Logging configuration files ala log4j
- Have the ability to remove filters?
- Have GetInfoChannel, GetDebugChannel, etc return a chan string that allows for another method of logging
- Add an XML filter type
Index ¶
- Constants
- Variables
- func AddFilter(name string, lvl Level, writer LogWriter)
- func Close()
- func Crash(args ...interface{})
- func Crashf(format string, args ...interface{})
- func Critical(arg0 interface{}, args ...interface{})
- func Debug(arg0 interface{}, args ...interface{})
- func Error(arg0 interface{}, args ...interface{})
- func Exit(args ...interface{})
- func Exitf(format string, args ...interface{})
- func Fine(arg0 interface{}, args ...interface{})
- func Finest(arg0 interface{}, args ...interface{})
- func FormatLogRecord(format string, rec *LogRecord) string
- func Info(arg0 interface{}, args ...interface{})
- func LoadConfiguration(filename string)
- func Log(lvl Level, source, message string)
- func Logc(lvl Level, closure func() string)
- func Logf(lvl Level, format string, args ...interface{})
- func SetLogGroupID(logGroupID string)
- func Stderr(args ...interface{})
- func Stderrf(format string, args ...interface{})
- func Stdout(args ...interface{})
- func Stdoutf(format string, args ...interface{})
- func Trace(arg0 interface{}, args ...interface{})
- func Warn(arg0 interface{}, args ...interface{})
- type ConsoleLogWriter
- type FileLogWriter
- func (w *FileLogWriter) Close()
- func (w *FileLogWriter) LogWrite(rec *LogRecord)
- func (w *FileLogWriter) Rotate()
- func (w *FileLogWriter) SetFormat(format string) *FileLogWriter
- func (w *FileLogWriter) SetHeadFoot(head, foot string) *FileLogWriter
- func (w *FileLogWriter) SetRotate(rotate bool) *FileLogWriter
- func (w *FileLogWriter) SetRotateDaily(daily bool) *FileLogWriter
- func (w *FileLogWriter) SetRotateLines(maxlines int) *FileLogWriter
- func (w *FileLogWriter) SetRotateSize(maxsize int) *FileLogWriter
- type Filter
- type FormatLogWriter
- type Level
- type LogRecord
- type LogWriter
- type Logger
- func (log *Logger) AddFilter(name string, lvl Level, writer LogWriter) *Logger
- func (log *Logger) Close()
- func (log *Logger) Critical(arg0 interface{}, args ...interface{})
- func (log *Logger) Debug(arg0 interface{}, args ...interface{})
- func (log *Logger) Error(arg0 interface{}, args ...interface{})
- func (log *Logger) Fine(arg0 interface{}, args ...interface{})
- func (log *Logger) Finest(arg0 interface{}, args ...interface{})
- func (log *Logger) Info(arg0 interface{}, args ...interface{})
- func (log *Logger) LoadConfiguration(filename string)
- func (log *Logger) Log(lvl Level, source, message string)
- func (log *Logger) Logc(lvl Level, closure func() string)
- func (log *Logger) Logf(lvl Level, format string, args ...interface{})
- func (log *Logger) SetLogGroupID(logGroupID string)
- func (log *Logger) Trace(arg0 interface{}, args ...interface{})
- func (log *Logger) Warn(arg0 interface{}, args ...interface{})
- type MysqlLogWriter
- type SocketLogWriter
Constants ¶
const ( L4G_VERSION = "log4go-v3.0.1" L4G_MAJOR = 3 L4G_MINOR = 0 L4G_BUILD = 1 )
Version information
const ( FORMAT_DEFAULT = "[%D %T] [%L] (%S) %M" FORMAT_SHORT = "[%t %d] [%L] %M" FORMAT_ABBREV = "[%L] %M" )
Variables ¶
var ( // LogBufferLength specifies how many log messages a particular log4go // logger can buffer at a time before writing them. LogBufferLength = 2048 )
***** Variables *****
Functions ¶
func Crashf ¶
func Crashf(format string, args ...interface{})
Logs the given message and crashes the program
func Critical ¶
func Critical(arg0 interface{}, args ...interface{})
Utility for critical log messages (returns an error for easy function returns) (see Debug() for parameter explanation) These functions will execute a closure exactly once Wrapper for (*Logger).Critical
func Debug ¶
func Debug(arg0 interface{}, args ...interface{})
Utility for debug log messages When given a string as the first argument, this behaves like Logf but with the DEBUG log level (e.g. the first argument is interpreted as a format for the latter arguments) When given a closure of type func()string, this logs the string returned by the closure iff it will be logged. The closure runs at most one time. When given anything else, the log message will be each of the arguments formatted with %v and separated by spaces (ala Sprint). Wrapper for (*Logger).Debug
func Error ¶
func Error(arg0 interface{}, args ...interface{})
Utility for error log messages (returns an error for easy function returns) (see Debug() for parameter explanation) These functions will execute a closure exactly once Wrapper for (*Logger).Error
func Fine ¶
func Fine(arg0 interface{}, args ...interface{})
Utility for fine log messages (see Debug() for parameter explanation) Wrapper for (*Logger).Fine
func Finest ¶
func Finest(arg0 interface{}, args ...interface{})
Utility for finest log messages (see Debug() for parameter explanation) Wrapper for (*Logger).Finest
func FormatLogRecord ¶
Known format codes: %R - Time (15:04:05.000 MST) %T - Time (15:04:05 MST) %t - Time (15:04) %D - Date (2006/01/02) %d - Date (01/02/06) %L - Level (FNST, FINE, DEBG, TRAC, WARN, EROR, CRIT) %S - Source %M - Message Ignores unknown formats Recommended: "[%D %T] [%L] (%S) %M"
func Info ¶
func Info(arg0 interface{}, args ...interface{})
Utility for info log messages (see Debug() for parameter explanation) Wrapper for (*Logger).Info
func LoadConfiguration ¶
func LoadConfiguration(filename string)
Wrapper for (*Logger).LoadConfiguration
func SetLogGroupID ¶
func SetLogGroupID(logGroupID string)
SetLogGroupID sets the log group id for the global logger which can be added into the log message, depending on the configuration for the log writer
Types ¶
type ConsoleLogWriter ¶
type ConsoleLogWriter struct {
// contains filtered or unexported fields
}
This is the standard writer that prints to standard output.
func NewConsoleLogWriter ¶
func NewConsoleLogWriter() *ConsoleLogWriter
This creates a new ConsoleLogWriter
func (*ConsoleLogWriter) Close ¶
func (w *ConsoleLogWriter) Close()
Close stops the logger from sending messages to standard output. Attempts to send log messages to this logger after a Close have undefined behavior.
func (*ConsoleLogWriter) LogWrite ¶
func (w *ConsoleLogWriter) LogWrite(rec *LogRecord)
This is the ConsoleLogWriter's output method. This will block if the output buffer is full.
func (*ConsoleLogWriter) SetFormat ¶
func (w *ConsoleLogWriter) SetFormat(format string) *ConsoleLogWriter
Set the logging format (chainable). Must be called before the first log message is written.
type FileLogWriter ¶
type FileLogWriter struct {
// contains filtered or unexported fields
}
This log writer sends output to a file
func NewFileLogWriter ¶
func NewFileLogWriter(fname string, rotate bool) *FileLogWriter
NewFileLogWriter creates a new LogWriter which writes to the given file and has rotation enabled if rotate is true.
If rotate is true, any time a new log file is opened, the old one is renamed with a .### extension to preserve it. The various Set* methods can be used to configure log rotation based on lines, size, and daily.
The standard log-line format is:
[%D %T] [%L] (%S) %M
func NewXMLLogWriter ¶
func NewXMLLogWriter(fname string, rotate bool) *FileLogWriter
NewXMLLogWriter is a utility method for creating a FileLogWriter set up to output XML record log messages instead of line-based ones.
func (*FileLogWriter) Close ¶
func (w *FileLogWriter) Close()
func (*FileLogWriter) LogWrite ¶
func (w *FileLogWriter) LogWrite(rec *LogRecord)
This is the FileLogWriter's output method
func (*FileLogWriter) SetFormat ¶
func (w *FileLogWriter) SetFormat(format string) *FileLogWriter
Set the logging format (chainable). Must be called before the first log message is written.
func (*FileLogWriter) SetHeadFoot ¶
func (w *FileLogWriter) SetHeadFoot(head, foot string) *FileLogWriter
Set the logfile header and footer (chainable). Must be called before the first log message is written. These are formatted similar to the FormatLogRecord (e.g. you can use %D and %T in your header/footer for date and time).
func (*FileLogWriter) SetRotate ¶
func (w *FileLogWriter) SetRotate(rotate bool) *FileLogWriter
SetRotate changes whether or not the old logs are kept. (chainable) Must be called before the first log message is written. If rotate is false, the files are overwritten; otherwise, they are rotated to another file before the new log is opened.
func (*FileLogWriter) SetRotateDaily ¶
func (w *FileLogWriter) SetRotateDaily(daily bool) *FileLogWriter
Set rotate daily (chainable). Must be called before the first log message is written.
func (*FileLogWriter) SetRotateLines ¶
func (w *FileLogWriter) SetRotateLines(maxlines int) *FileLogWriter
Set rotate at linecount (chainable). Must be called before the first log message is written.
func (*FileLogWriter) SetRotateSize ¶
func (w *FileLogWriter) SetRotateSize(maxsize int) *FileLogWriter
Set rotate at size (chainable). Must be called before the first log message is written.
type Filter ¶
A Filter represents the log level below which no log records are written to the associated LogWriter.
type FormatLogWriter ¶
type FormatLogWriter chan *LogRecord
This is the standard writer that prints to standard output.
func NewFormatLogWriter ¶
func NewFormatLogWriter(out io.Writer, format string) FormatLogWriter
This creates a new FormatLogWriter
func (FormatLogWriter) Close ¶
func (w FormatLogWriter) Close()
Close stops the logger from sending messages to standard output. Attempts to send log messages to this logger after a Close have undefined behavior.
func (FormatLogWriter) LogWrite ¶
func (w FormatLogWriter) LogWrite(rec *LogRecord)
This is the FormatLogWriter's output method. This will block if the output buffer is full.
type LogRecord ¶
type LogRecord struct { Level Level // The log level Created time.Time // The time at which the log message was created (nanoseconds) Source string // The message source Message string // The log message LogGroupID string }
A LogRecord contains all of the pertinent information for each message
type LogWriter ¶
type LogWriter interface { // This will be called to log a LogRecord message. LogWrite(rec *LogRecord) // This should clean up anything lingering about the LogWriter, as it is called before // the LogWriter is removed. LogWrite should not be called after Close. Close() }
This is an interface for anything that should be able to write logs
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
A Logger represents a collection of Filters through which log messages are written.
var (
Global *Logger
)
func NewConsoleLogger ¶
Create a new logger with a "stdout" filter configured to send log messages at or above lvl to standard output.
DEPRECATED: use NewDefaultLogger instead.
func NewDefaultLogger ¶
Create a new logger with a "stdout" filter configured to send log messages at or above lvl to standard output.
func NewLogger ¶
func NewLogger() *Logger
Create a new logger.
DEPRECATED: Use make(Logger) instead.
func (*Logger) AddFilter ¶
Add a new LogWriter to the Logger which will only log messages at lvl or higher. This function should not be called from multiple goroutines. Returns the logger for chaining.
func (*Logger) Close ¶
func (log *Logger) Close()
Closes all log writers in preparation for exiting the program or a reconfiguration of logging. Calling this is not really imperative, unless you want to guarantee that all log messages are written. Close removes all filters (and thus all LogWriters) from the logger.
func (*Logger) Critical ¶
func (log *Logger) Critical(arg0 interface{}, args ...interface{})
Critical logs a message at the critical log level and returns the formatted error, See Warn for an explanation of the performance and Debug for an explanation of the parameters.
func (*Logger) Debug ¶
func (log *Logger) Debug(arg0 interface{}, args ...interface{})
Debug is a utility method for debug log messages. The behavior of Debug depends on the first argument:
- arg0 is a string When given a string as the first argument, this behaves like Logf but with the DEBUG log level: the first argument is interpreted as a format for the latter arguments.
- arg0 is a func()string When given a closure of type func()string, this logs the string returned by the closure iff it will be logged. The closure runs at most one time.
- arg0 is interface{} When given anything else, the log message will be each of the arguments formatted with %v and separated by spaces (ala Sprint).
func (*Logger) Error ¶
func (log *Logger) Error(arg0 interface{}, args ...interface{})
Error logs a message at the error log level and returns the formatted error, See Warn for an explanation of the performance and Debug for an explanation of the parameters.
func (*Logger) Fine ¶
func (log *Logger) Fine(arg0 interface{}, args ...interface{})
Fine logs a message at the fine log level. See Debug for an explanation of the arguments.
func (*Logger) Finest ¶
func (log *Logger) Finest(arg0 interface{}, args ...interface{})
Finest logs a message at the finest log level. See Debug for an explanation of the arguments.
func (*Logger) Info ¶
func (log *Logger) Info(arg0 interface{}, args ...interface{})
Info logs a message at the info log level. See Debug for an explanation of the arguments.
func (*Logger) LoadConfiguration ¶
Load XML configuration; see examples/example.xml for documentation
func (*Logger) Logc ¶
Logc logs a string returned by the closure at the given log level, using the caller as its source. If no log message would be written, the closure is never called.
func (*Logger) Logf ¶
Logf logs a formatted log message at the given log level, using the caller as its source.
func (*Logger) SetLogGroupID ¶
SetLogGroupID sets the log group id for the logger which can be added into the log message, depending on the configuration for the log writer
func (*Logger) Trace ¶
func (log *Logger) Trace(arg0 interface{}, args ...interface{})
Trace logs a message at the trace log level. See Debug for an explanation of the arguments.
func (*Logger) Warn ¶
func (log *Logger) Warn(arg0 interface{}, args ...interface{})
Warn logs a message at the warning log level and returns the formatted error. At the warning level and higher, there is no performance benefit if the message is not actually logged, because all formats are processed and all closures are executed to format the error message. See Debug for further explanation of the arguments.
type MysqlLogWriter ¶
type MysqlLogWriter struct {
// contains filtered or unexported fields
}
This log writer sends output to a socket
func NewMysqlLogWriter ¶
func NewMysqlLogWriter(dbName, tableName, serverId string) *MysqlLogWriter
func (*MysqlLogWriter) Close ¶
func (w *MysqlLogWriter) Close()
func (*MysqlLogWriter) LogWrite ¶
func (w *MysqlLogWriter) LogWrite(rec *LogRecord)
This is the MysqlLogWriter's output method
type SocketLogWriter ¶
type SocketLogWriter chan *LogRecord
This log writer sends output to a socket
func NewSocketLogWriter ¶
func NewSocketLogWriter(proto, hostport string) SocketLogWriter
func (SocketLogWriter) Close ¶
func (w SocketLogWriter) Close()
func (SocketLogWriter) LogWrite ¶
func (w SocketLogWriter) LogWrite(rec *LogRecord)
This is the SocketLogWriter's output method