miss

miss

Package miss provides an flexible, extensible and powerful logging management tool based on the level, which has done the better balance between the flexibility and the performance.

miss is meaning:

1. love: Because of loving it, I miss it.
2. flexible and extensible: Something can be customized according to demand, so they are missing.
3. no any third-party dependencies: for the core package, you don't care any other packages, including the third-party.

It is inspired by log15, logrus, go-kit.

See the GoDoc.

Basic Principle

• The better performance
• Flexible, extensible, and powerful
• No any third-party dependencies

Features

• A simple, easy-to-understand API
• No any third-party dependencies for the core package.
• A flexible and powerful interface supporting many encoders, such as the Key-Value or Format style encoder
• Child loggers which inherit and add their own private context
• Lazy evaluation of expensive operations
• Support the native io.Writer as the output, and provied some advanced io.Writer implementations, such as MultiWriter and LevelWriter.
• Built-in support for logging to files, syslog, and the network

Logger

type Logger interface {
	// Depth returns a new Logger with the stack depth.
	//
	// stackDepth is the calling depth of the logger, which will be passed to
	// the encoder. The default depth is the global variable DefaultLoggerDepth
	// for the new Logger.
	//
	// It should be used typically when you wrap the logger. For example,
	//
	//   logger := miss.New(miss.KvTextEncoder(os.Stdout))
	//   logger = logger.Depth(logger.GetDepth() + 1)
	//
	//   func Debug(m string, args ...interface{}) { logger.Debug(m, args...) }
	//   func Info(m string, args ...interface{}) { logger.Debug(m, args...) }
	//   func Warn(m string, args ...interface{}) { logger.Debug(m, args...) }
	//   ...
	//
	Depth(stackDepth int) Logger

	// Level returns a new Logger with the new level.
	Level(level Level) Logger

	// Encoder returns a new logger with the new encoder.
	Encoder(encoder Encoder) Logger

	// Ctx returns a new logger with the new contexts.
	Cxt(ctxs ...interface{}) Logger

	GetDepth() int
	GetLevel() Level
	GetEncoder() Encoder

	Trace(msg string, args ...interface{}) error
	Debug(msg string, args ...interface{}) error
	Info(msg string, args ...interface{}) error
	Warn(msg string, args ...interface{}) error
	Error(msg string, args ...interface{}) error
	Panic(msg string, args ...interface{}) error
	Fatal(msg string, args ...interface{}) error
}

Example

1. Prepare a writer having implemented io.Writer, such as os.Stdout.
2. Create an encoder.
3. Create a logger with the encoder.
4. Output the log.

package main

import (
	"os"

	"github.com/xgfone/miss"
)

func main() {
	conf := miss.EncoderConfig{IsLevel: true, IsTime: true}
	encoder := miss.KvTextEncoder(os.Stdout, conf)
	logger := miss.New(encoder).Level(miss.WARN)

	logger.Info("don't output")
	logger.Error("will output", "key", "value")
	// Output:
	// t=2018-10-25T10:46:22.0035694+08:00 lvl=ERROR key=value msg=will output
}

Notice:

miss is based on the level, and the log output interfaces is func(string, ...interface{}) error, the meaning of the arguments of which is decided by the encoder. See below.

Furthermore, miss has built in a global logger, which is equal to miss.New(miss.KvTextEncoder(os.Stdout, miss.EncoderConfig{IsLevel: true, IsTime: true})), and you can use the functions as follow:

SetGlobalLogger(newLogger Logger)
GetGlobalLogger() Logger

WithLevel(level Level) Logger
WithEncoder(encoder Encoder) Logger
WithCtx(ctxs ...interface{}) Logger
WithDepth(depth int) Logger

GetDepth() int
GetLevel() Level
GetEncoder() Encoder

Trace(msg string, args ...interface{}) error
Debug(msg string, args ...interface{}) error
Info(msg string, args ...interface{}) error
Warn(msg string, args ...interface{}) error
Error(msg string, args ...interface{}) error
Panic(msg string, args ...interface{}) error
Fatal(msg string, args ...interface{}) error

If you prefer the logger without the error, you maybe use LoggerWithoutError converted by ToLoggerWithoutError(Logger) from Logger as follow:

type LoggerWithoutError interface {
	Depth(stackDepth int) LoggerWithoutError
	Level(level Level) LoggerWithoutError
	Encoder(encoder Encoder) LoggerWithoutError
	Cxt(ctxs ...interface{}) LoggerWithoutError

	GetDepth() int
	GetLevel() Level
	GetEncoder() Encoder

	Trace(msg string, args ...interface{})
	Debug(msg string, args ...interface{})
	Info(msg string, args ...interface{})
	Warn(msg string, args ...interface{})
	Error(msg string, args ...interface{})
	Panic(msg string, args ...interface{})
	Fatal(msg string, args ...interface{})
}

Inherit the context of the parent logger

encoder := FmtTextEncoder(os.Stdout)
parent := logger.New(encoder).Ctx("parent")
child := parent.Ctx("child")
child.Info("hello %s", "world")
// Output:
// [parent][child] :=>: hello world

OR

parent := logger.New("key1", "value1")
child := parent.New("key2", "value2").Encoder(KvTextEncoder(os.Stdout))
child.Info("hello world", "key3", "value3")
// Output:
// key1=value1 key2=value2 key3=value3 msg=hello world

Encoder

The core package provides three kinds of encoders: the text encoder based on Key-Value KvTextEncoder, the text encoder based on Format FmtTextEncoder and the json encoder based on Key-Value KvStdJSONEncoder and KvSimpleJSONEncoder.

For the encoders based on Format, the arguments of the log output function, such as Info(), are the same as those of fmt.Sprintf(). For the encoders based on Key-Value, but, the first argument is the log description, and the rests are the key-value pairs, the number of which are even, for example, logger.Info("log description", "key1", "value1", "key2", "value2").

kvlog := miss.New(miss.KvTextEncoder(os.Stdout))
kvlog.Info("creating connection", "host", "127.0.0.1", "port", 80)

fmtlog := miss.New(miss.FmtTextEncoder(os.Stdout))
kvlog.Info("creating connection to %s:%d", "127.0.0.1", 80)

LevelFilterEncoder and MultiEncoder

You can use LevelFilterEncoder to filter some logs by the level, for example,

encoders := ["kvtext", "kvjson"]
textenc := miss.KvTextEncoder(os.Stdout)
jsonenc := miss.KvSimpleJSONEncoder(os.Stderr)

textenc = miss.LevelFilterEncoder(miss.INFO, textenc)
jsonenc = miss.LevelFilterEncoder(miss.ERROR, jsonenc)

logger := miss.New(miss.MultiEncoder(textenc, jsonenc))

if err := logger.Info("only output to stdout"); err != nil {
    for i, e := range err.(miss.MultiError) {
        fmt.Printf("%s: %s\n", encoders[i], e.Error())
    }
}

if err := logger.Error("output to stdout & stderr); err != nil {
    for i, e := range err.(miss.MultiError) {
        fmt.Printf("%s: %s\n", encoders[i], e.Error())
    }
}

Writer

All implementing the interface io.Writer are a Writer.

There are some the built-in writers in the core package, such as DiscardWriter, NetWriter, FileWriter, MultiWriter, FailoverWriter, SafeWriter, ChannelWriter, BufferedWriter, LevelFilterWriter, SyslogWriter, SyslogNetWriter, SizedRotatingFileWriter and Must.

MultiWriter

For an encoder, you can output the result to more than one destination by using MultiWriter. For example, output the log to STDOUT and the file:

writer := miss.MultiWriter(os.Stdout, miss.FileWriter("/path/to/file"))
encoder := miss.KvTextEncoder(writer)
logger := miss.New(encoder)

logger.Info("output to stdout and file")

Lazy evaluation

If the type of a certain value is Valuer, the default encoder engine will call it and encode the returned result. For example,

logger := miss.New("hello", func(d int, l Level) (interface{}, error) { return "world", nil })

or

logger.Info("hello %v", func(d int, l Level) (interface{}, error) { return "world", nil })

Performance

The log framework itself has no any performance costs.

There may be some performance costs below:

1. Use format arguments or Key-Value pairs when firing a log. For example, logger.Info("hello %s", "world") will allocate the 16-byte memory once for the encoder FmtTextEncoder , logger.Info("hello world", "key", "value") will allocate the 32-byte memory once for the encoder KvTextEncoder.
2. Encode the arguments to io.Writer. For string or []byte, there is no any performance cost, but for other types, such as int, it maybe have once memory allocation.

Performance Test

The test program is from go-loggers-bench.

MacBook Pro(Retina, 13-inch, Mid 2014)
2.6 GHz Intel Core i5
8 GB 1600 MHz DDR3
macOS Mojave

TextNegative

TextPositive

JSONNegative

JSONPositive

NOTICE: For pursuing the extreme performance, you maybe see zerolog.