- Notifications
You must be signed in to change notification settings - Fork17
Dead simple, super fast, zero allocation logger for Golang
License
francoispqt/onelog
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Onelog is a dead simple but very efficient JSON logger.It is one of the fastest JSON logger out there. Also, it is one of the logger with the lowest allocation.
It gives more control over log levels enabled by using bitwise operation for setting levels on a logger.
It is also modular as you can add a custom hook, define level text values, level and message keys.
Go 1.9 is required as it uses a type alias over gojay.Encoder.
It is named onelog as a reference to zerolog and because it sounds likeOne Love song from Bob Marley :)
go get github.com/francoispqt/onelog
Basic usage:
import"github.com/francoispqt/onelog"funcmain() {// create a new Logger// first argument is an io.Writer// second argument is the level, which is an integerlogger:=onelog.New(os.Stdout,onelog.ALL,// shortcut for onelog.DEBUG|onelog.INFO|onelog.WARN|onelog.ERROR|onelog.FATAL, )logger.Info("hello world !")// {"level":"info","message":"hello world"}}
Levels are ints mapped to a string. The logger will check if level is enabled with an efficient bitwise &(AND), if disabled, it returns right away which makes onelog the fastest when running disabled logging with 0 allocs and less than 1ns/op.See benchmarks
When creating a logger you must use the| operator with different levels to toggle bytes.
Example if you want levels INFO and WARN:
logger:=onelog.New(os.Stdout,onelog.INFO|onelog.WARN,)
This allows you to have a logger with different levels, for example you can do:
varlogger*onelog.Loggerfuncinit() {// if we are in debug mode, enable DEBUG lvlifos.Getenv("DEBUG")!="" {logger=onelog.New(os.Stdout,onelog.ALL,// shortcut for onelog.DEBUG|onelog.INFO|onelog.WARN|onelog.ERROR|onelog.FATAL )return }logger=onelog.New(os.Stdout,onelog.INFO|onelog.WARN|onelog.ERROR|onelog.FATAL, )}
Available levels:
- onelog.DEBUG
- onelog.INFO
- onelog.WARN
- onelog.ERROR
- onelog.FATAL
You can change their textual values by doing, do this only once at runtime as it is not thread safe:
onelog.LevelText(onelog.INFO,"INFO")
You can define a hook which will be run for every log message.
Example:
logger:=onelog.New(os.Stdout,onelog.ALL,)logger.Hook(func(e onelog.Entry) {e.String("time",time.Now().Format(time.RFC3339))})logger.Info("hello world !")// {"level":"info","message":"hello world","time":"2018-05-06T02:21:01+08:00"}
Context allows enforcing a grouping format where all logs fields key-values pairs from all logging methods (With, Info, Debug, InfoWith, InfoWithEntry, ...etc) exceptfor values from usinglogger.Hook, will be enclosed in giving context name provided as it's key. For example using a context key "params" as below
logger:=onelog.NewContext(os.Stdout,onelog.INFO|onelog.WARN,"params")logger.InfoWithFields("breaking news !",func(e onelog.Entry) {e.String("userID","123455")})// {"level":"info","message":"breaking news !", "params":{"userID":"123456"}}
This principle also applies when inheriting from a previous created logger as below
parentLogger:=onelog.New(os.Stdout,onelog.INFO|onelog.WARN,)logger:=parentLogger.WithContext("params")logger.InfoWithFields("breaking news !",func(e onelog.Entry) {e.String("userID","123455")})// {"level":"info","message":"breaking news !", "params":{"userID":"123456"}}
You can always reset the context by callingWithContext("") to create a no-context logger from acontext logger parent.
Logging without extra fields is easy as:
logger:=onelog.New(os.Stdout,onelog.ALL,)logger.Debug("i'm not sure what's going on")// {"level":"debug","message":"i'm not sure what's going on"}logger.Info("breaking news !")// {"level":"info","message":"breaking news !"}logger.Warn("beware !")// {"level":"warn","message":"beware !"}logger.Error("my printer is on fire")// {"level":"error","message":"my printer is on fire"}logger.Fatal("oh my...")// {"level":"fatal","message":"oh my..."}
Logging with extra fields is quite simple, specially if you have used gojay:
logger:=onelog.New(os.Stdout,onelog.ALL,)logger.DebugWithFields("i'm not sure what's going on",func(e onelog.Entry) {e.String("string","foobar")e.Int("int",12345)e.Int64("int64",12345)e.Float("float64",0.15)e.Bool("bool",true)e.Err("err",errors.New("someError"))e.ObjectFunc("user",func(eEntry) {e.String("name","somename") })})// {"level":"debug","message":"i'm not sure what's going on","string":"foobar","int":12345,"int64":12345,"float64":0.15,"bool":true,"err":"someError","user":{"name":"somename"}}logger.InfoWithFields("breaking news !",func(e onelog.Entry) {e.String("userID","123455")})// {"level":"info","message":"breaking news !","userID":"123456"}logger.WarnWithFields("beware !",func(e onelog.Entry) {e.String("userID","123455")})// {"level":"warn","message":"beware !","userID":"123456"}logger.ErrorWithFields("my printer is on fire",func(e onelog.Entry) {e.String("userID","123455")})// {"level":"error","message":"my printer is on fire","userID":"123456"}logger.FatalWithFields("oh my...",func(e onelog.Entry) {e.String("userID","123455")})// {"level":"fatal","message":"oh my...","userID":"123456"}
Alternatively, you can use the chain syntax:
logger.InfoWith("foo bar").Int("testInt",1).Int64("testInt64",2).Float("testFloat",1.15234).String("testString","string").Bool("testBool",true).ObjectFunc("testObj",func(eEntry) {e.Int("testInt",100) }).Object("testObj2",testObj).// implementation of gojay.MarshalerJSONObjectArray("testArr",testArr).// implementation of gojay.MarshalerJSONArrayErr("testErr",errors.New("my printer is on fire !")).Write()// don't forget to call this method!
You can create get a logger with some accumulated context that will be included on all logs created by this logger.
To do that, you must call theWith method on a logger.Internally it creates a copy of the current logger and returns it.
Example:
logger:=onelog.New(os.Stdout,onelog.ALL,).With(func(e onelog.Entry) {e.String("userID","123456")})logger.Info("user logged in")// {"level":"info","message":"user logged in","userID":"123456"}logger.Debug("wtf?")// {"level":"debug","message":"wtf?","userID":"123456"}logger.ErrorWithFields("Oops",func(e onelog.Entry) {e.String("error_code","ROFL")})// {"level":"error","message":"oops","userID":"123456","error_code":"ROFL"}
You can change globally the levels values by calling the function:
onelog.LevelText(onelog.INFO,"INFO")
You can change the key of the message by calling the function:
onelog.MsgKey("msg")
You can change the key of the level by calling the function:
onelog.LevelKey("lvl")
Beware, these changes are global (affects all instances of the logger). Also, these function should be called only once at runtime to avoid any data race issue.
For thorough benchmarks please see the results in the bench suite created by the author of zerolog here:https://github.com/rs/logbench
The benchmarks data presented below is the one from Uber's benchmark suite where we added onelog.
Benchmarks are here:https://github.com/francoispqt/zap/tree/onelog-bench/benchmarks
| ns/op | bytes/op | allocs/op | |
|---|---|---|---|
| Zap | 8.73 | 0 | 0 |
| zerolog | 2.45 | 0 | 0 |
| logrus | 12.1 | 16 | 1 |
| onelog | 0.74 | 0 | 0 |
| ns/op | bytes/op | allocs/op | |
|---|---|---|---|
| Zap | 208 | 768 | 5 |
| zerolog | 68.7 | 128 | 4 |
| logrus | 721 | 1493 | 12 |
| onelog | 1.31 | 0 | 0 |
| onelog-chain | 68.2 | 0 | 0 |
| ns/op | bytes/op | allocs/op | |
|---|---|---|---|
| Zap | 205 | 0 | 0 |
| zerolog | 135 | 0 | 0 |
| logrus | 1256 | 1554 | 24 |
| onelog | 84.8 | 0 | 0 |
| ns/op | bytes/op | allocs/op | |
|---|---|---|---|
| Zap | 276 | 0 | 0 |
| zerolog | 141 | 0 | 0 |
| logrus | 1256 | 1554 | 24 |
| onelog | 82.4 | 0 | 0 |
| ns/op | bytes/op | allocs/op | |
|---|---|---|---|
| Zap | 1764 | 770 | 5 |
| zerolog | 1210 | 128 | 4 |
| logrus | 13211 | 13584 | 129 |
| onelog | 971 | 128 | 4 |
| onelog-chain | 1030 | 128 | 4 |
About
Dead simple, super fast, zero allocation logger for Golang