#go-logging
[
go-logging is a high-performance logging library for golang.
- Simple: It supports only necessary operations and easy to get start.
- Fast: Asynchronous logging without runtime-related fields has an extremely low delay of about 800 nano-seconds.
- Performance in my laptop as follow.
BenchmarkSync 300000 4472 ns/op
BenchmarkAsync 300000 4503 ns/op
BenchmarkBasicSync 500000 2869 ns/op
BenchmarkBasicAsync 500000 2963 ns/op
BenchmarkPrintln 1000000 1474 ns/opThe step below will download the library source code to
${GOPATH}/src/github.com/ccding/go-logging.
go get github.com/ccding/go-logging/loggingGiven the source code downloaded, it makes you be able to run the examples, tests, and benchmarks.
cd ${GOPATH}/src/github.com/ccding/go-logging/logging
go get
go run ../example.go
go test -v -bench .go-logging is used like any other Go libraries. You can simply use the library in this way.
import "github.com/ccding/go-logging/logging"Here is a simple example.
package main
import (
"github.com/ccding/go-logging/logging"
)
func main() {
logger, _ := logging.SimpleLogger("main")
logger.Error("this is a test from error")
logger.Destroy()
}It has the following functions to create a logger.
// with BasicFormat and writing to stdout
SimpleLogger(name string) (*Logger, error)
// with BasicFormat and writing to DefaultFileName
BasicLogger(name string) (*Logger, error)
// with RichFormatand writing to DefaultFileName
RichLogger(name string) (*Logger, error)
// with detailed configuration and writing to file
FileLogger(name string, level Level, format string, timeFormat string, file string, sync bool) (*Logger, error)
// with detailed configuration and writing to a writer
WriterLogger(name string, level Level, format string, timeFormat string, out io.Writer, sync bool) (*Logger, error)
// read configurations from a config file
ConfigLogger(filename string) (*Logger, error)The meanings of these fields are
name string // logger name
level Level // record level higher than this will be printed
format string // format configuration
timeFormat string // format for time
file string // file name for logging
out io.Writer // writer for logging
sync bool // use sync or async way to record logsThe detailed description of these fields will be presented later.
It supports the following functions for logging. All of these functions are thread-safe.
(*Logger) Logf(level Level, format string, v ...interface{})
(*Logger) Log(level Level, v ...interface{})
(*Logger) Criticalf(format string, v ...interface{})
(*Logger) Critical(v ...interface{})
(*Logger) Fatalf(format string, v ...interface{})
(*Logger) Fatal(v ...interface{})
(*Logger) Errorf(format string, v ...interface{})
(*Logger) Error(v ...interface{})
(*Logger) Warningf(format string, v ...interface{})
(*Logger) Warning(v ...interface{})
(*Logger) Warnf(format string, v ...interface{})
(*Logger) Warn(v ...interface{})
(*Logger) Infof(format string, v ...interface{})
(*Logger) Info(v ...interface{})
(*Logger) Debugf(format string, v ...interface{})
(*Logger) Debug(v ...interface{})
(*Logger) Notsetf(format string, v ...interface{})
(*Logger) Notset(v ...interface{})The logger supports the following operations. In these functions, SetWriter
and Destroy are not thread-safe, while others are. All these functions are
running in a synchronous way.
// Getter functions
(*Logger) Name() string // get name
(*Logger) TimeFormat() string // get time format
(*Logger) Level() Level // get level [this function is thread safe]
(*Logger) RecordFormat() string // get the first part of the format
(*Logger) RecordArgs() []string // get the second part of the format
(*Logger) Writer() io.Writer // get writer
(*Logger) Sync() bool // get sync or async
// Setter functions
(*Logger) SetLevel(level Level) // set level [this function is thread safe]
(*Logger) SetWriter(out ...io.Writer) // set multiple writers
// Other functions
(*Logger) Flush() // flush the writer
(*Logger) Destroy() // destroy the loggerName field is a string, which can be written to the logging and used to separate multiple loggers. It allows two logger having the same name. There is not any default value for name.
There are these levels in logging.
CRITICAL 50
FATAL CRITICAL
ERROR 40
WARNING 30
WARN WARNING
INFO 20
DEBUG 10
NOTSET 0The record format is described by a string, which has two parts separated by
\n. The first part describes the format of the log, and the second part
lists all the fields to be shown in the log. In other word, the first part is
the first parameter format of fmt.Printf(format string, v ...interface{}),
and the second part describes the second parameter v of it. It is not
allowed to have \n in the first part. The fields in the second part are
separated by comma ,, while extra blank spaces are allowed. An example of
the format string is
const BasicFormat = "%s [%6s] %30s - %s\n name,levelname,time,message"which is the pre-defined BasicFormat used by BasicLogger() and
SimpleLogger().
It supports the following fields for the second part of the format.
"name" string %s // name of the logger
"seqid" uint64 %d // sequence number
"levelno" int32 %d // level number
"levelname" string %s // level name
"created" int64 %d // starting time of the logger
"nsecs" int64 %d // nanosecond of the starting time
"time" string %s // record created time
"timestamp" int64 %d // timestamp of record
"rtime" int64 %d // relative time since started
"filename" string %s // source filename of the caller
"pathname" string %s // filename with path
"module" string %s // executable filename
"lineno" int %d // line number in source code
"funcname" string %s // function name of the caller
"process" int %d // process id
"message" string %s // logger messageThe following runtime-related fields is extremely expensive and slow, please be careful when using them.
"filename" string %s // source filename of the caller
"pathname" string %s // filename with path
"lineno" int %d // line number in source code
"funcname" string %s // function name of the callerThere are a few pre-defined values for record format.
BasicFormat = "%s [%6s] %30s - %s\n name,levelname,time,message"
RichFormat = "%s [%6s] %d %30s - %d - %s:%s:%d - %s\n name, levelname, seqid, time, filename, funcname, lineno, message"We use the same time format as golang. The default time format is
DefaultTimeFormat = "2006-01-02 15:04:05.999999999" // default time formatThe meaning of these fields are obvious. Filename is used to create writer.
We also allow the user create a writer by herself and pass it to the logger.
Sync describes whether the user would like to use synchronous or asynchronous
method to write logs. true value means synchronous method, and false value
means asynchronous way. We suggest you use asynchronous way because it causes
extremely low extra delay by the logging functions.
In alphabetical order
- Cong Ding ([ccding][ccding])
- Xiang Li ([xiangli-cmu][xiangli])
- Zifei Tong ([5kg][5kg]) [ccding]: //github.com/ccding [xiangli]: //github.com/xiangli-cmu [5kg]: //github.com/5kg