wtflog

Wtflog

Wtflog is a logging library that provides convenient logging APIs like standard log and logrus, but more efficient in recording complex structures (with gen-bsa).

Usage

Basic

package main

import "gitee.com/FlyingOnion/wtflog"

func main() {
    logger := wtflog.NewTextLogger()
    logger.Info("hello world")
    // output:
    // hello world
}

Struct, Map, Slice

For complex structures (struct, map, slice), log them with gen-bsa:

1. go install gitee.com/FlyingOnion/gen-bsa
2. cd to root directory and run gen-bsa, and the code generator will generate helper functions AppendTo in wtf__.go file
3. use logging functions

type FooStruct struct {
    S string
    I int
}

type FooSlice []FooStruct

type FooMap map[string]FooStruct

Part of generated code:

func (p FooStruct) AppendTo(b *ByteSlice) {
	var any interface{}
	_ = any
	b.AppendString("{S:")
	b.AppendString(p.S)
	b.AppendString(" I:")
	b.AppendInt64(int64(p.I))
	b.AppendByte('}')
}

func (p FooSlice) AppendTo(b *ByteSlice) {
	if p == nil { b.AppendString("<nil>"); return }
	var any interface{}
	_ = any
	b.AppendByte('[')
	for i, elem := range p {
		if i > 0 { b.AppendByte(' ') }
		any = elem
		if bsa, ok := any.(ByteSliceAppender); ok { bsa.AppendTo(b) } else if str, ok := any.(Stringer); ok { b.AppendString(str.String()) } else { b.AppendString(fmtPrint(any)) }
	}
	b.AppendByte(']')
}

func (p FooMap) AppendTo(b *ByteSlice) {
	if p == nil { b.AppendString("<nil>"); return }
	if len(p) == 0 { b.AppendString("{}"); return }
	var any interface{}
	_ = any
	b.AppendByte('{')
	kvs := make([]struct{k string; v interface{}}, 0, len(p))
	for k, v := range p { kvs = append(kvs, struct{k string; v interface{}}{k: string(k), v: interface{}(v)}) }
	sortKeys(kvs, func(i, j int) bool { return kvs[i].k < kvs[j].k })
	for i, kv := range kvs {
		if i > 0 { b.AppendByte(' ') }
		b.AppendString(kv.k)
		b.AppendByte(':')
		any = kv.v
		if bsa, ok := any.(ByteSliceAppender); ok { bsa.AppendTo(b) } else if str, ok := any.(Stringer); ok { b.AppendString(str.String()) } else { b.AppendString(fmtPrint(any)) }
	}
	b.AppendByte('}')
}

package main

import "gitee.com/FlyingOnion/wtflog"

func main() {
	foo := FooStruct{S: "hello", I: 8}
	fooSlice := FooSlice([]FooStruct{foo})
	fooMap := FooMap(map[string]FooStruct{"foo": foo})
	l := wtflog.NewTextLogger()
	l.Info(foo, fooSlice, fooMap)
    // output:
    // {S:hello I:8} [{S:hello I:8}] {foo:{S:hello I:8}}
}

With Field Log Level, Time, and Caller

We provide WithFieldsAtFront and WithFieldsAtBack function if you want to add fields.

Available fields are: FieldCaller, FieldLevel, FieldTime. All fields are formatted in default way "key=value"

l := wtflog.NewTextLogger().WithFieldsAtFront(FieldLevel, FieldTime).WithFieldsAtBack(FieldCaller)
l.Info("hello world")
// output:
// level=info time=2022-05-23 10:03:21 hello world caller=c:/Users/Administrator/go/src/.../logger_test.go:22

Logger Initialization

We suggest you init and set global logger if the logger is used widely in your program.

import "gitee.com/FlyingOnion/wtflog"

func InitLogger() {
    // Available options:
    // WithFieldsAtFront
    // WithFieldsAtBack
    // WithCallerSkip
    logger := wtflog.NewTextLogger().
        WithLogLevel(wtflog.LevelDebug).
        WithWriter(yourWriter)
    wtflog.SetGlobalLogger(logger)
    // you can use wtflog.Info, wtflog.Error directly with your custom logger now.
}

Work Progress

• text logger: 80%
• json logger: 80%
• formatted logger (f methods): TODO
• code generator gen-bsa: 90%

Why Another Logging Library

We researched current logging libraries (including popular logrus, go-kit/log, zap, zerolog), and found a disappointing phenomenon. Almost all libraries (even those claiming zero allocations) failed to find a more effective way to record complex structures (struct, map, slice, array, pointer). All they do is to pass the arguments to fmt.Sprint or fmt.Sprintf.

In wtflog, things will be changed.

The design philosophy of wtflog is to move the place that decides logging format of a variable from fmt to the variable itself as much as possible. This method is quite different from convention, and you may need to take some time to adapt it.

import "gitee.com/FlyingOnion/wtflog"
import . "gitee.com/FlyingOnion/wtflog/types"

func Log() {
    logger := wtflog.NewTextLogger()
    logger.Info("Hello world")
    logger.Info(1)      // bad
    logger.Info(Int(1)) // good
    logger.Info(time.Now())       // bad
    logger.Info(Time(time.Now())) // good
}

In the example above, 1 is an integer and it does not bring any information about how it will be logged (it will be decided by fmt). As a contrast, Int type is a custom type that brings these information. See the declaration of Int:

type Int int
func (i Int) AppendTo(b *ByteSlice) { b.AppendInt64(int64(i)) }
func (i Int) String() string        { return strconv.FormatInt(int64(i), 10) }

The AppendTo function implements ByteSliceAppender interface, which could be distinguished by wtflog, so that it could skip fmt type check and directly append to logging buffer b. This method is similar with what zap and zerolog do.

The type-check process of wtflog is quite simple. Suppose the argument is v (interface{})

1. If v is nil, write <nil>.
2. Check whether v is a []byte, string, ByteSliceAppender, Stringer successively. If matched then use corresponding write method.
3. If either is not matched use fmt.Sprintf("%+v", v) and write that string.

We imagine that if each argument is either a []byte, string, ByteSliceAppender, Stringer, the logging efficiency will be improved dramatically, compared with standard log and logrus.

For basic types (except string and []byte), we provide the Int and Uint family, Float, Time, and Duration.

// Assume that you have already
// import . "gitee.com/FlyingOnion/wtflog/types"

logger.Info(Int(1)) // or Int8(1), Int16(1), Int32(1), Int64(1)
logger.Info(Uint(1)) // or Uint8(1), Uint16(1), Uint32(1), Uint64(1)
logger.Info(Float32(1.0)) // or Float64(1.0)
logger.Info(Float32f(1.0, 'e', 2)) // or Float64f with format and precision
logger.Info(Time(time.Now())) // "2006-01-02 15:04:05" format
logger.Info(Timef(time.Now(), time.RFC3339)) // RFC3339 format
logger.Info(Timestamp(time.Now())) // or TimestampMilli, TimestampMicro, TimestampNano
logger.Info(Duration(1*time.Second))
logger.Info(Error(io.EOF))

Level Writer

The concept of level writer is similar with the one of logrus. We provide a builtin level writer. Usage of level writer is shown below.

// set os.Stdout as default writer.
// set a level writer map.
levelWriter := NewLevelWriter(os.Stdout, map[wtflog.Level]io.Writer{
    wtflog.LevelWarn:  os.Stderr,
    wtflog.LevelError: os.Stderr,
})
logger := NewTextLogger().WithWriter(levelWriter)