README
¶
gogger
A Go library for logging.
Overview
gogger is a logging library, providing just one Log struct and Logger interface.
This is to simplify instance creation and to ensure that the exact same approach can always be taken.
Log struct is designed to be highly extensible, using the LogWriter interface for log output
and the LogFormatter interface for log formatting, which can be freely replaced.
Also, multiple LogWriters can be configured for Log,
so that the same log can be written to both stdout and a file, for example.
Since LogWriter and LogFormatter are exported interfaces,
users are free to define and use them if they are dissatisfied with the built-in ones.
If they are useful, please give us pull request.
Quickstart
Here is an example of using the built-in LogStreamWriter and LogSimpleFormatter.
Those details are described after this section.
Remember that Log generation is done here by passing only LogConfig to its constructor, NewLog.
Then, configure LogWriter and LogFormatter in LogConfig.
package main
import (
"github.com/yackrru/gogger"
"os"
"time"
)
func main() {
writer := gogger.NewLogStreamWriter(gogger.LogStreamWriterOption{
Output: os.Stderr,
})
writer.Open()
defer writer.Close(2 * time.Minute)
logger := gogger.NewLog(&gogger.LogConfig{
Writers: []gogger.LogWriter{writer},
Formatter: gogger.NewLogSimpleFormatter(gogger.DefaultLogSimpleFormatterTmpl),
})
// logging
logger.Info("log string")
}
LogConfig
It is a centralized setting for Log.
| option | default | description |
|---|---|---|
| Writers | - | Set a LogWriter for each output destination. |
| Formatter | - | Only one LogFormatter can be set. |
| TimeFormat | "2006-01-02 15:04:05.000" |
Time stamp format. Specify a time format string for the golang. |
| LogMinLevel | INFO | Specify the log level you want to output. Log levels are ERROR, WARN, INFO, DEBUG, and OFF. |
Writer
LogStreamWriter
It is an asynchronous log writer with an internal FIFO queue (channel to be exact) of log strings and a log output goroutine. Performance is adjusted the capacity of the channel as a FIFO queue and the interval between log outputs.
gogger.NewLogStreamWriter(gogger.LogStreamWriterOption{
Output: os.Stderr,
SyncIntervalMills: 100,
SyncQueueSize: 50000,
})
| option | default | description |
|---|---|---|
| Output | os.Stderr | Specify the *os.File to which the logs will be output. |
| SyncIntervalMills | 100 | The log output interval. (milliseconds) |
| SyncQueueSize | 10000 | The capacity of the channel as a FIFO queue. (0 - 65,535) |
Formatter
LogSimpleFormatter
It is a LogFormatter that formats a predefined parameter and log string in a format set as a template. The struct itself has only one parameter, a template string called tmpl, which is passed to the constructor when the instance is created.
gogger.NewLogSimpleFormatter(gogger.DefaultLogSimpleFormatterTmpl)
| option | default | description |
|---|---|---|
| tmpl | "%timestamp% %level% --- [%pkg%] %args%" |
The template string. Each parameter is enclosed in %. %args% is the string passed to Log. |
Documentation
¶
Index ¶
Constants ¶
const (
DefaultLogSimpleFormatterTmpl = "%timestamp% %level% --- [%pkg%] %args%"
)
const (
DefaultTimeFormat = "2006-01-02 15:04:05.000"
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Log ¶
type Log struct {
// contains filtered or unexported fields
}
Log is the top-level logger instance. However, it is only an abstracted entrypoint, and need to set LogWriter for output and LogFormatter for formatting.
func (*Log) AddWriters ¶
AddWriters adds LogWriter to Log.
type LogConfig ¶
type LogConfig struct {
// Multiple LogWriters can be configured to output logs to multiple destinations.
Writers []LogWriter
// Only one LogFormatter can be set per Log instance.
Formatter LogFormatter
// The default value for TimeFormat is DefaultTimeFormat.
TimeFormat string
// The default value for LogMinLevel is LevelInfo.
LogMinLevel LogLevel
}
LogConfig is the configurations of Log. There is no way to configure settings directly in the Log, and can only change settings through this config.
type LogFormatter ¶
LogFormatter is the interface that wraps the standard method of Format.
type LogSimpleFormatter ¶
type LogSimpleFormatter struct {
// contains filtered or unexported fields
}
LogSimpleFormatter implements LogFormatter. It outputs simple flat string has params that are timestamp, level, pkg and args. Set each parameter in tmpl freely arranged by enclosing each parameter in % like %timestamp%. The default value of tmpl is DefaultLogSimpleFormatterTmpl. The args param is identical to the args passed in the Logger interface method.
func NewLogSimpleFormatter ¶
func NewLogSimpleFormatter(tmpl string) *LogSimpleFormatter
func (*LogSimpleFormatter) Format ¶
func (f *LogSimpleFormatter) Format(timestamp, level, pkg string, args ...interface{}) string
type LogStreamWriter ¶
type LogStreamWriter struct {
// contains filtered or unexported fields
}
LogStreamWriter implements LogWriter. It is an asynchronous log writer with an internal FIFO queue (channel to be exact) of log strings and a log output goroutine.
func NewLogStreamWriter ¶
func NewLogStreamWriter(opts LogStreamWriterOption) *LogStreamWriter
NewLogStreamWriter creates LogStreamWriter but does not start logging. Execute LogStreamWriter.Open is required to start logging.
func (*LogStreamWriter) Close ¶
func (w *LogStreamWriter) Close(timeout time.Duration)
Close terminates acceptance of logs and outputs logs accumulated in the queue. However, since asynchronous goroutine is output while synchronizing, a timeout is set, and synchronization is terminated when the timeout is exceeded.
func (*LogStreamWriter) Open ¶
func (w *LogStreamWriter) Open()
Open starts synchronization of the output goroutine.
func (*LogStreamWriter) Write ¶
func (w *LogStreamWriter) Write(msg string)
type LogStreamWriterOption ¶
type LogStreamWriterOption struct {
// Output is the log output destination.
// Default is os.Stderr.
Output *os.File
// SyncIntervalMills is the log output interval.
// Default is 100.
SyncIntervalMills int64
// SyncQueueSize is the log string queue size.
// Default is 10000.
SyncQueueSize uint16
}
LogStreamWriterOption is the options of LogStreamWriter. There is no way to configure options directly in the LogStreamWriter, and can only change settings through this option.
Source Files