README
¶
clog (console-log)
All the fashionable loggers for Go tend to focus on structured logging, and that's perfectly fine: until you simply need a logger for a console application...
So here's yet another logger for Go:
- unstructured logging
- console logging in colour
- file logging
- simple to use
- filter your logs from 5 levels of severity (Trace, Debug, Info, Warn, Error)
- redirect your logs to an io.Writer
- get logs coming from an io.Writer
- using the logger from the standard library under the hood
- extensible (via handlers and middleware)
- unit test coverage of more than 90%
- drop-in replacement for the standard library logger
Have a look at the examples if you like the look of it
Here's a very simple one:
import "github.com/creativeprojects/clog"
func main() {
log := clog.NewFilteredConsoleLogger(clog.LevelInfo)
log.Debug("will be discarded")
log.Info("will be displayed")
}
Documentation available on GoDoc
Documentation
¶
Index ¶
- Variables
- func CloseTestLog()
- func Debug(v ...interface{})
- func Debugf(format string, v ...interface{})
- func Error(v ...interface{})
- func Errorf(format string, v ...interface{})
- func Info(v ...interface{})
- func Infof(format string, v ...interface{})
- func Log(level LogLevel, v ...interface{})
- func Logf(level LogLevel, format string, v ...interface{})
- func SetDefaultLogger(logger *Logger)
- func SetTestLog(t TestLogInterface)
- func Stderr() io.Writer
- func Stdout() io.Writer
- func Trace(v ...interface{})
- func Tracef(format string, v ...interface{})
- func Warning(v ...interface{})
- func Warningf(format string, v ...interface{})
- type AsyncHandler
- type ConsoleHandler
- type DiscardHandler
- type FileHandler
- type Handler
- type LevelFilter
- type LogEntry
- type LogLevel
- type Logger
- func (l *Logger) Debug(v ...interface{})
- func (l *Logger) Debugf(format string, v ...interface{})
- func (l *Logger) Error(v ...interface{})
- func (l *Logger) Errorf(format string, v ...interface{})
- func (l *Logger) GetHandler() Handler
- func (l *Logger) Info(v ...interface{})
- func (l *Logger) Infof(format string, v ...interface{})
- func (l *Logger) Log(level LogLevel, v ...interface{})
- func (l *Logger) LogEntry(logEntry LogEntry) error
- func (l *Logger) Logf(level LogLevel, format string, v ...interface{})
- func (l *Logger) SetHandler(handler Handler)
- func (l *Logger) SetPrefix(prefix string) Handler
- func (l *Logger) Trace(v ...interface{})
- func (l *Logger) Tracef(format string, v ...interface{})
- func (l *Logger) Warning(v ...interface{})
- func (l *Logger) Warningf(format string, v ...interface{})
- type MemoryHandler
- type MiddlewareHandler
- type SafeHandler
- type SafeWriter
- type StandardLogHandler
- type StandardLogger
- func (l *StandardLogger) Fatal(v ...interface{})
- func (l *StandardLogger) Fatalf(format string, v ...interface{})
- func (l *StandardLogger) Fatalln(v ...interface{})
- func (l *StandardLogger) Panic(v ...interface{})
- func (l *StandardLogger) Panicf(format string, v ...interface{})
- func (l *StandardLogger) Panicln(v ...interface{})
- func (l *StandardLogger) Print(v ...interface{})
- func (l *StandardLogger) Printf(format string, v ...interface{})
- func (l *StandardLogger) Println(v ...interface{})
- func (l *StandardLogger) RegisterExitFunc(exitFunc func()) *StandardLogger
- type TestHandler
- type TestLogInterface
- type TextHandler
- type Writer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNoRegisteredHandler = errors.New("no registered handler") ErrHandlerClosed = errors.New("handler is closed") ErrMessageDiscarded = errors.New("this message is not going anywhere") ErrNoPrimaryHandler = errors.New("no primary handler registered") ErrNoBackupHandler = errors.New("no backup handler registered") )
All errors that can be returned by the clog package
Functions ¶
func CloseTestLog ¶ added in v0.1.0
func CloseTestLog()
CloseTestLog at the end of the test otherwise the logger will keep a reference on t. For a description on how to use it, see SetTestLog()
func Errorf ¶
func Errorf(format string, v ...interface{})
Errorf sends error information to the console
func Log ¶
func Log(level LogLevel, v ...interface{})
Log sends a log entry with the specified level
func SetDefaultLogger ¶
func SetDefaultLogger(logger *Logger)
SetDefaultLogger sets the logger used when using the package methods
func SetTestLog ¶
func SetTestLog(t TestLogInterface)
SetTestLog install a test logger as the default logger. A test logger redirects all logs sent through the package methods to the Log/Logf methods of your test
IMPORTANT: don't forget to CloseTestLog() at the end of the test
Example:
func TestLog(t *testing.T) {
SetTestLog(t)
defer CloseTestLog()
// These two calls are equivalent:
clog.Debug("debug message")
t.Log("debug message")
}
func Stderr ¶ added in v0.4.0
Stderr returns a thread-safe io.Writer to os.Stderr. Calling this function multiple times always returns the same instance of io.Writer.
func Stdout ¶ added in v0.4.0
Stdout returns a thread-safe io.Writer to os.Stdout. Calling this function multiple times always returns the same instance of io.Writer.
func Trace ¶ added in v0.6.0
func Trace(v ...interface{})
Trace sends trace information for heavy debugging
Types ¶
type AsyncHandler ¶ added in v0.7.0
type AsyncHandler struct {
// contains filtered or unexported fields
}
AsyncHandler asynchronously send log messages to the next handler in the chain
Example ¶
// Close the async handler before finishing your application or you might miss the last few log messages
handler := NewAsyncHandler(NewTextHandler("async ", 0))
defer handler.Close()
logger := NewLogger(handler)
logger.Info("hello world")
Output: async hello world
func NewAsyncHandler ¶ added in v0.7.0
func NewAsyncHandler(destination Handler) *AsyncHandler
NewAsyncHandler returns a handler that sends logs asynchronously.
func NewAsyncHandlerWithCapacity ¶ added in v0.7.0
func NewAsyncHandlerWithCapacity(next Handler, capacity uint) *AsyncHandler
NewAsyncHandlerWithCapacity returns a handler that sends logs asynchronously.
func (*AsyncHandler) Close ¶ added in v0.7.0
func (h *AsyncHandler) Close()
Close blocks until all log messages have been delivered
func (AsyncHandler) GetHandler ¶ added in v0.7.0
func (h AsyncHandler) GetHandler() Handler
GetHandler returns the next handler in the chain
func (*AsyncHandler) LogEntry ¶ added in v0.7.0
func (h *AsyncHandler) LogEntry(logEntry LogEntry) error
LogEntry sends the log message asynchronously to the next handler. Please note the call will block when the buffer capacity is reached. It will return an error if there's no "next" handler, of if we called the Close method. Otherwise it will always return nil as it doesn't know if the message will be delivered.
func (AsyncHandler) SetHandler ¶ added in v0.7.0
func (h AsyncHandler) SetHandler(handler Handler)
SetHandler sets the next handler in the chain
func (*AsyncHandler) SetPrefix ¶ added in v0.7.0
func (h *AsyncHandler) SetPrefix(prefix string) Handler
SetPrefix sets a prefix on every log message
type ConsoleHandler ¶
type ConsoleHandler struct {
// contains filtered or unexported fields
}
ConsoleHandler logs messages to the console (in colour)
func NewConsoleHandler ¶
func NewConsoleHandler(prefix string, flag int) *ConsoleHandler
NewConsoleHandler creates a new handler to send logs to the console
func (*ConsoleHandler) Colouring ¶
func (h *ConsoleHandler) Colouring(colouring bool) *ConsoleHandler
Colouring activate of deactivate displaying messages in colour in the console, and returns the ConsoleHandler for chaining.
func (*ConsoleHandler) LogEntry ¶
func (h *ConsoleHandler) LogEntry(logEntry LogEntry) error
LogEntry sends a log entry with the specified level
func (*ConsoleHandler) SetPrefix ¶ added in v0.5.0
func (h *ConsoleHandler) SetPrefix(prefix string) Handler
SetPrefix sets a prefix on every log message, and returns the Handler interface for chaining.
func (*ConsoleHandler) SetTheme ¶
func (h *ConsoleHandler) SetTheme(theme string) *ConsoleHandler
SetTheme sets a new color theme, and returns the ConsoleHandler for chaining. Accepted values are: "none", "light", "dark"
type DiscardHandler ¶
type DiscardHandler struct{}
DiscardHandler forgets any log message
func NewDiscardHandler ¶ added in v0.4.0
func NewDiscardHandler() *DiscardHandler
NewDiscardHandler returns a handler that forgets all the logs you throw at it.
func (*DiscardHandler) LogEntry ¶
func (h *DiscardHandler) LogEntry(LogEntry) error
LogEntry discards the LogEntry
func (*DiscardHandler) SetPrefix ¶ added in v0.5.0
func (h *DiscardHandler) SetPrefix(string) Handler
SetPrefix sets a prefix on every log message
type FileHandler ¶
type FileHandler struct {
*StandardLogHandler
// contains filtered or unexported fields
}
FileHandler logs messages to a file
func NewFileHandler ¶
func NewFileHandler(filename string, prefix string, flag int) (*FileHandler, error)
NewFileHandler creates a new file logger
Remember to Close() the logger at the end
func (*FileHandler) Close ¶
func (l *FileHandler) Close()
Close the logfile when no longer needed
please note this method reinstate the standard console output as default
type Handler ¶
Handler for a logger.
The LogEntry method should return an error if the handler didn't manage to save the log (file, remote, etc.) It's up to the parent handler to take action on the error: the default Logger is always going to ignore it.
type LevelFilter ¶
type LevelFilter struct {
// contains filtered or unexported fields
}
LevelFilter is a log middleware that is only passing log entries of level >= minimum level
Example ¶
logger := NewLogger(NewLevelFilter(LevelInfo, NewTextHandler("", 0)))
logger.Debug("won't be displayed")
logger.Info("hello world")
Output: hello world
func NewLevelFilter ¶
func NewLevelFilter(minLevel LogLevel, destination Handler) *LevelFilter
NewLevelFilter creates a new LevelFilter handler passing log entries to destination if level >= minimum level
func (*LevelFilter) GetHandler ¶
func (h *LevelFilter) GetHandler() Handler
GetHandler returns the current handler used by the filter
func (*LevelFilter) LogEntry ¶
func (h *LevelFilter) LogEntry(logEntry LogEntry) error
LogEntry the LogEntry
func (*LevelFilter) SetHandler ¶
func (h *LevelFilter) SetHandler(handler Handler)
SetHandler sets a new handler for the filter
func (*LevelFilter) SetLevel ¶
func (h *LevelFilter) SetLevel(minLevel LogLevel) *LevelFilter
SetLevel changes the minimum level the log entries are going to be sent to the destination logger
func (*LevelFilter) SetPrefix ¶ added in v0.5.0
func (h *LevelFilter) SetPrefix(prefix string) Handler
SetPrefix sets a prefix on every log message
type LogEntry ¶
type LogEntry struct {
Calldepth int // Calldepth is used to calculate the right place where we called the log method
Level LogLevel // Debug, Info, Warning or Error
Format string // Format for *printf (leave blank for *print)
Values []interface{} // Values for *print and *printf
}
LogEntry represents a log entry
func NewLogEntry ¶ added in v0.5.0
NewLogEntry creates a new LogEntry composed of values.
values parameter is comparable to fmt.Sprint(values...)
func NewLogEntryf ¶ added in v0.5.0
NewLogEntryf creates a new formatted LogEntry with values.
parameters are comparable to fmt.Sprintf(format, values...)
func (LogEntry) GetMessage ¶
GetMessage returns the formatted message from Format & Values
func (LogEntry) GetMessageWithLevelPrefix ¶
GetMessageWithLevelPrefix returns the formatted message from Format & Values prefixed with the level name
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger frontend
func GetDefaultLogger ¶
func GetDefaultLogger() *Logger
GetDefaultLogger returns the logger used when using the package methods
func NewConsoleLogger ¶
func NewConsoleLogger() *Logger
NewConsoleLogger is a shortcut to create a Logger with a ConsoleHandler
func NewFilteredConsoleLogger ¶
NewFilteredConsoleLogger is a shortcut to create a Logger with a FilteredHandler sending to a ConsoleHandler
func (*Logger) Error ¶
func (l *Logger) Error(v ...interface{})
Error sends error information to the console
func (*Logger) GetHandler ¶
GetHandler returns the current handler used by the logger
func (*Logger) SetHandler ¶
SetHandler sets a new handler for the logger
func (*Logger) Trace ¶ added in v0.6.0
func (l *Logger) Trace(v ...interface{})
Trace sends trace information for heavy debugging
type MemoryHandler ¶
type MemoryHandler struct {
// contains filtered or unexported fields
}
MemoryHandler save messages in memory (useful for unit testing).
func NewMemoryHandler ¶
func NewMemoryHandler() *MemoryHandler
NewMemoryHandler creates a new MemoryHandler that keeps logs in memory.
func (*MemoryHandler) LogEntry ¶
func (h *MemoryHandler) LogEntry(logEntry LogEntry) error
LogEntry keep the message in memory.
func (*MemoryHandler) SetPrefix ¶ added in v0.5.0
func (h *MemoryHandler) SetPrefix(prefix string) Handler
SetPrefix adds a prefix to every log message. Please note no space is added between the prefix and the log message
type MiddlewareHandler ¶ added in v0.7.0
MiddlewareHandler is a Handler that act as a middleware => you can get and set the next handler in the chain
type SafeHandler ¶
type SafeHandler struct {
// contains filtered or unexported fields
}
SafeHandler sends logs to an alternate destination when the primary destination fails
Example ¶
// a safe handler is a middleware with two targets (Handler):
// - it will send all messages to the primary handler
// - it will only send the messages again to the backup handler if the primary returned an error
// let's create a safe handler with these two targets: a DiscardHandler and a TextHandler
// the DiscardHandler is a special handler that always discards your log messages and returns an error
logger := NewLogger(NewSafeHandler(NewDiscardHandler(), NewTextHandler("backup ", 0)))
logger.Infof("hello %s", "world")
Output: backup hello world
func NewSafeHandler ¶
func NewSafeHandler(primary, backup Handler) *SafeHandler
NewSafeHandler creates a handler that redirects logs to a backup handler when the primary fails
func (*SafeHandler) LogEntry ¶
func (h *SafeHandler) LogEntry(logEntry LogEntry) error
LogEntry send messages to primaryHandler first, then to backupHandler if it had fail
func (*SafeHandler) SetPrefix ¶ added in v0.5.0
func (h *SafeHandler) SetPrefix(prefix string) Handler
SetPrefix sets a prefix on every log message
type SafeWriter ¶ added in v0.4.0
type SafeWriter struct {
// contains filtered or unexported fields
}
SafeWriter is a thread safe io.Writer
func NewSafeWriter ¶ added in v0.4.0
func NewSafeWriter(writer io.Writer) *SafeWriter
NewSafeWriter creates a thread-safe io.Writer
type StandardLogHandler ¶
type StandardLogHandler struct {
// contains filtered or unexported fields
}
StandardLogHandler send messages to a io.Writer using the standard logger.
func NewStandardLogHandler ¶
func NewStandardLogHandler(out io.Writer, prefix string, flag int) *StandardLogHandler
NewStandardLogHandler creates a handler to send the logs to io.Writer through a standard logger.
func (*StandardLogHandler) LogEntry ¶
func (h *StandardLogHandler) LogEntry(logEntry LogEntry) error
LogEntry sends a log entry with the specified level.
func (*StandardLogHandler) SetOutput ¶
func (h *StandardLogHandler) SetOutput(output io.Writer) *StandardLogHandler
SetOutput sets the output destination for the logger.
func (*StandardLogHandler) SetPrefix ¶ added in v0.5.0
func (h *StandardLogHandler) SetPrefix(prefix string) Handler
SetPrefix sets a prefix on every log message
type StandardLogger ¶ added in v0.2.0
type StandardLogger struct {
// contains filtered or unexported fields
}
StandardLogger can be used when you need to plug-in a standard library logger (via an interface)
func NewStandardLogger ¶ added in v0.2.0
func NewStandardLogger(level LogLevel, handler Handler) *StandardLogger
NewStandardLogger creates a new logger that can be used in place of a standard library logger (via an interface)
func (*StandardLogger) Fatal ¶ added in v0.2.0
func (l *StandardLogger) Fatal(v ...interface{})
Fatal is equivalent to l.Print() followed by a call to os.Exit(1). You can change the exit function with RegisterExitFunc if needed.
func (*StandardLogger) Fatalf ¶ added in v0.2.0
func (l *StandardLogger) Fatalf(format string, v ...interface{})
Fatalf is equivalent to l.Printf() followed by a call to os.Exit(1). You can change the exit function with RegisterExitFunc if needed.
func (*StandardLogger) Fatalln ¶ added in v0.2.0
func (l *StandardLogger) Fatalln(v ...interface{})
Fatalln is equivalent to l.Println() followed by a call to os.Exit(1). You can change the exit function with RegisterExitFunc if needed.
func (*StandardLogger) Panic ¶ added in v0.2.0
func (l *StandardLogger) Panic(v ...interface{})
Panic is equivalent to l.Print() followed by a call to panic().
func (*StandardLogger) Panicf ¶ added in v0.2.0
func (l *StandardLogger) Panicf(format string, v ...interface{})
Panicf is equivalent to l.Printf() followed by a call to panic().
func (*StandardLogger) Panicln ¶ added in v0.2.0
func (l *StandardLogger) Panicln(v ...interface{})
Panicln is equivalent to l.Println() followed by a call to panic().
func (*StandardLogger) Print ¶ added in v0.2.0
func (l *StandardLogger) Print(v ...interface{})
Print writes the output for a logging event. Arguments are handled in the manner of fmt.Print. A newline is appended if the last character of s is not already a newline.
func (*StandardLogger) Printf ¶ added in v0.2.0
func (l *StandardLogger) Printf(format string, v ...interface{})
Printf writes the output for a logging event. Arguments are handled in the manner of fmt.Printf. A newline is appended if the last character of s is not already a newline.
func (*StandardLogger) Println ¶ added in v0.2.0
func (l *StandardLogger) Println(v ...interface{})
Println writes the output for a logging event. Arguments are handled in the manner of fmt.Println.
func (*StandardLogger) RegisterExitFunc ¶ added in v0.7.0
func (l *StandardLogger) RegisterExitFunc(exitFunc func()) *StandardLogger
RegisterExitFunc allows using a different "exit" function when calling Fatal, Fatalln or Fatalf. If not specified, os.Exit(1) is used
type TestHandler ¶
type TestHandler struct {
// contains filtered or unexported fields
}
TestHandler redirects all the logs to the testing framework logger
func NewTestHandler ¶
func NewTestHandler(t TestLogInterface) *TestHandler
NewTestHandler instantiates a new logger redirecting to the test framework logger or any other implementation of TestLogInterface for that matter
func (*TestHandler) LogEntry ¶
func (h *TestHandler) LogEntry(logEntry LogEntry) error
LogEntry sends a log entry with the specified level
func (*TestHandler) SetPrefix ¶ added in v0.5.0
func (h *TestHandler) SetPrefix(prefix string) Handler
SetPrefix does nothing on the test handler
type TestLogInterface ¶
type TestLogInterface interface {
Log(args ...interface{})
Logf(format string, args ...interface{})
}
TestLogInterface for use with testing.B or testing.T
type TextHandler ¶ added in v0.5.0
type TextHandler struct {
// contains filtered or unexported fields
}
TextHandler logs messages directly to the console
Example ¶
logger := NewLogger(NewTextHandler("example ", 0))
logger.Info("hello world")
Output: example hello world
func NewTextHandler ¶ added in v0.5.0
func NewTextHandler(prefix string, flag int) *TextHandler
NewTextHandler creates a new handler to send logs to the console
func (*TextHandler) LogEntry ¶ added in v0.5.0
func (h *TextHandler) LogEntry(logEntry LogEntry) error
LogEntry sends a log entry with the specified level
func (*TextHandler) SetPrefix ¶ added in v0.5.0
func (h *TextHandler) SetPrefix(prefix string) Handler
SetPrefix sets a prefix on every log message
type Writer ¶ added in v0.3.0
type Writer struct {
// contains filtered or unexported fields
}
Writer is an io.Writer that writes into a Handler. This can be used to redirect a log.Logger into a handler.
Example ¶
// a writer can be used to redirect logs coming from a standard logger
writer := NewWriter(LevelError, NewTextHandler("", 0))
// create a http server with a standard log.Logger redirecting to our writer
server := &http.Server{
ErrorLog: log.New(writer, "http", 0),
}
server.Close()
Source Files
Directories