slog

package module
v1.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 14, 2019 License: MIT Imports: 11 Imported by: 46

README

Slf4go Build Status

Simple logger facade for Golang, inspired by slf4j, which focused on performance and scalability.

Introduction

Before introducing this library, let's walk through the composition of logging library.

  1. Provide API: like Trade Debug Info Warn Error etc.
  2. Collect Info: like timestamp, stacktrace, and other context fields etc.
  3. Format & Store: print log into stdout or store it directly etc.

For most logging library, 1 and 2 is quite similar, but different libraries may use different logging libraries, if your project dependents multi libraries, the final log could be very messy.

In the java language, most libraries use slf4j as its logging facade, you can decide to use logback or log4j etc as real logging implementation, and switch it easily.

I believe there should have similar "facade" in golang, and i hope this library could be golang's slf4j.

slf4go focus on 1 and 2, and will collect all information to build an integrated Log instance, it expect other library provide 3 implementation, for more details, check Driver section.

The structure of standard Log is:

type Log struct {
	Time   int64  `json:"date"`   // log's time(us)
	Logger string `json:"logger"` // log's name, default is package

	Pid        int     `json:"pid"`         // the process id which generated this log
	Gid        int     `json:"gid"`         // the goroutine id which generated this log
	DebugStack *string `json:"debug_stack"` // the debug stack of this log. Only for Panic and Fatal
	Stack      *Stack  `json:"stack"`       // the stack info of this log. Contains {Package, Filename, Function, Line}

	Level  Level         `json:"level"`  // log's level
	Format *string       `json:"format"` // log's format
	Args   []interface{} `json:"args"`   // log's format args
	Fields Fields        `json:"fields"` // additional custom fields
}

What need special explanation is, slf4go has very high performance, for more details, check Performance section.

Components

slf4go have several components:

  • Log: Log record's structure, contains Time, Logger, Pid, Gid, Stack, Fields, etc.
  • Logger: Provide api for Trace, Debug, Info, Warn, Error, Panic, Fatal etc.
  • Driver: It's an interface, used for decoupling Api and Implementation.
  • Hook: Provide a hook feature, can be used for log's synchronous callback.

For better understanding, check this chart:

Usage

This section provides complete instructions on how to install and use slf4go.

Install

Could use this command to install slf4go:

go get github.com/go-eden/slf4go

Could import slf4go like this:

import (
	slog "github.com/go-eden/slf4go"
)

Use Global Logger

By default, Slf4go provided a global Logger, in most case, you can use it directly by static function, don't need any other operation.

slog.Debugf("debug time: %v", time.Now())
slog.Warn("warn log")
slog.Error("error log")
slog.Panicf("panic time: %v", time.Now())

The final log is like this:

2019-06-16 19:35:05.167 [0] [TRACE] [main] default_example.go:12 debug time: 2019-06-16 19:35:05.167783 +0800 CST m=+0.000355435
2019-06-16 19:35:05.168 [0] [ WARN] [main] default_example.go:15 warn log
2019-06-16 19:35:05.168 [0] [ERROR] [main] default_example.go:17 error log
2019-06-16 19:35:05.168 [0] [PANIC] [main] default_example.go:20 panic time: 2019-06-16 19:35:05.168064 +0800 CST m=+0.000636402
goroutine 1 [running]:
runtime/debug.Stack(0x10aab40, 0xc0000b4100, 0x1)
	/usr/local/Cellar/go/1.12.6/libexec/src/runtime/debug/stack.go:24 +0x9d
github.com/go-eden/slf4go.Panicf(0x10cfd89, 0xe, 0xc0000b40f0, 0x1, 0x1)
	/Users/sulin/workspace/go-eden/slf4go/slf_core.go:191 +0x80
main.main()
	/Users/sulin/workspace/go-eden/slf4go/example/default_example.go:20 +0x213

What needs additional explanation is that panic and fatal will print goroutine stack automatically.

Use Your Own Logger

You can create your own Logger for other purposes:

log1 := slog.GetLogger() // Logger's name will be package name, like "main" or "github.com/go-eden/slf4go" etc
log1.Info("hello")
log2 := slog.NewLogger("test") // Logger's name will be the specified "test"
log2.Info("world")

The name of log1 will be caller's package name, like main or github.com/go-eden/slf4go etc, it depends on where you call it. The name of log2 will be the specified test.

Those name are important:

  • It would be fill into the final log directly.
  • It would be used to check if logging is enabled.
  • It would be used to decide whether and where to record the log.

Use Fields

You could use BindFields to add fields into the specified Logger, and use WithFields to create new Logger with the specified fields.

log1 := slog.GetLogger()
log1.BindFields(slog.Fields{"age": 18})
log1.Debug("hell1")

log1.WithFields(slog.Fields{"fav": "basketball"}).Warn("hello2")

log2 := log1.WithFields(slog.Fields{"fav": "basketball"})
log2.Info("hello2")

The fields will be attached to Log, and finally passed to Driver, the Driver decided how to print or where to store them.

Use Level

You can setup global level by SetLevel, which means the lower level log will be ignored.

slog.SetLevel(slog.WarnLevel)
slog.Info("no log") // will be ignored
slog.Error("error")

Above code setup global level to be WARN, so INFO log will be ignored, there should have other way to config different loggers' level, it based on which Driver you use.

You can check the specified level was enabled or not like this:

l := slog.GetLogger()
if l.IsDebugEnabled() {
    l.Debug("debug....")
}

In this example, slf4go will ask Driver whether accept DEBUG log of current logger, this process should cost few nanoseconds.

In fact, Logger will call IsDebugEnabled() in the Debug() function to filter unnecessary log, but this can't avoid the performance loss of preparing Debug()'s arguments, like string's concat.

As a comparison, preparing data and building Log would cost hundreds nanoseconds.

Use Hook

In slf4go, it's very easy to register log hook:

slog.RegisterHook(func(l *Log) {
    println(l) // you better not log again, it could be infinite loop 
})
slog.Debugf("are you prety? %t", true)

The RegisterHook accept func(*Log) argument, and slf4go will broadcast all Log to it asynchronously.

Driver

Driver is the bridge between the upper slf4go and the lower logging implementation.

// Driver define the standard log print specification
type Driver interface {
	// Retrieve the name of current driver, like 'default', 'logrus'...
	Name() string

	// Print responsible of printing the standard Log
	Print(l *Log)

	// Retrieve log level of the specified logger,
	// it should return the lowest Level that could be print,
	// which can help invoker to decide whether prepare print or not.
	GetLevel(logger string) Level
}

You can provider your own implementation, and replace the default driver.

Default StdDriver

By default, slf4go provides a StdDriver as fallback, it will format Log and print it into stdout directly, if you don't need other features, could use it directly.

This Driver will print log like this:

2019-06-16 19:35:05.168 [0] [ERROR] [github.com/go-eden/slf4go] default_example.go:17 error log

It contains these information:

  • 2019-06-16 19:35:05.168: Log's datetime.
  • [0]: Log's gid, the id of goroutine, like thread-id, it could be used for tracing.
  • [ERROR]: Log's level.
  • [github.com/go-eden/slf4go]: the caller's logger, it's package name by default.
  • default_example.go:17: the caller's filename and line.
  • error log: message, if level is PANIC or FATAL, DebugStack will be print too.

Other information was ignored, like fields pid etc.

Provide your own driver

You could implement a Driver easily, this is an example:

type MyDriver struct {}

func (*MyDriver) Name() string {
	return "my_driver"
}

func (*MyDriver) Print(l *slog.Log) {
    // print log, save db, send remote, etc.
}

func (*MyDriver) GetLevel(logger string) Level {
	return InfoLevel
}

func func init() {
	slog.SetDriver(new(MyDriver))
}

Above code provided an empty Driver, which means all log will be ignored totally.

Use slf4go-classic

TODO

Use slf4go-logrus

This is a simple Driver implementation for bridging slf4go and logrus.

I haven't used logrus too much, so this library don't have lots of features currently, hope you can help me improve this library, any Pull Request will be very welcomed.

https://github.com/go-eden/slf4go-logrus

Performance

This section's benchmark was based on MacBook Pro (15-inch, 2018).

When using empty Driver, the performace of slf4go is like this:

BenchmarkLogger-12    	 3000000	       420 ns/op	     112 B/op	       2 allocs/op

Which means if your Driver handles Log asychronously, log function like Debug Info Warn Error will complete in 500ns.

Here are some optimization points, hope it can help someone.

stack

Normally, you can obtain caller's trace Frame by runtime.Caller and runtime.FuncForPC, slf4go caches Frame for pc, which is a big performance boost.

In my benchmark, it improved performace from 430ns to 180ns, For more details, you can check source code.

etime

slf4go use etime to get system time, compared to time.Now(), etime.CurrentMicrosecond() has better performance.

In my benchmark, it improved performance from 68ns to 40ns.

License

MIT

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Debug

func Debug(v ...interface{})

Debug record debug level's log

func Debugf

func Debugf(format string, v ...interface{})

Debugf record debug level's log with custom format.

func Error

func Error(v ...interface{})

Error record error level's log

func Errorf

func Errorf(format string, v ...interface{})

Errorf record error level's log with custom format.

func Fatal

func Fatal(v ...interface{})

Fatal record fatal level's log

func Fatalf

func Fatalf(format string, v ...interface{})

Fatalf record fatal level's log with custom format.

func GetContext

func GetContext() string

GetContext obtain the global context name

func Info

func Info(v ...interface{})

Info record info level's log

func Infof

func Infof(format string, v ...interface{})

Infof record info level's log with custom format.

func Panic

func Panic(v ...interface{})

Panic record panic level's log

func Panicf

func Panicf(format string, v ...interface{})

Panic record panic level's log with custom format

func RegisterHook

func RegisterHook(f func(*Log))

RegisterHook register a hook, all log will inform it

func SetContext

func SetContext(name string)

SetContext update the global context name

func SetDriver

func SetDriver(d Driver)

SetDriver update the global log driver

func SetLevel

func SetLevel(l Level)

SetLevel update the global level, all lower level will not be send to driver to print

func Trace

func Trace(v ...interface{})

Trace record trace level's log

func Tracef

func Tracef(format string, v ...interface{})

Tracef record trace level's log with custom format.

func Warn

func Warn(v ...interface{})

Warn record warn level's log

func Warnf

func Warnf(format string, v ...interface{})

Warnf record warn level's log with custom format.

Types

type Driver

type Driver interface {
	// Retrieve the name of current driver, like 'default', 'logrus'...
	Name() string

	// Print responsible of printing the standard Log
	Print(l *Log)

	// Retrieve log level of the specified logger,
	// it should return the lowest Level that could be print,
	// which can help invoker to decide whether prepare print or not.
	GetLevel(logger string) Level
}

Driver define the standard log print specification

type Fields

type Fields map[string]interface{}

Fields represents attached fileds of log

func NewFields

func NewFields(fields ...Fields) Fields

Merge multi fileds into new Fields instance

type Level

type Level int

Log level

const (
	TraceLevel Level = iota
	DebugLevel
	InfoLevel
	WarnLevel
	ErrorLevel
	PanicLevel
	FataLevel
)

func (Level) String

func (l Level) String() string

Retrieve Level's name

type Log

type Log struct {
	Time   int64  `json:"date"`   // log's time(us)
	Logger string `json:"logger"` // log's name, default is package

	Pid        int     `json:"pid"`         // the process id which generated this log
	Gid        int     `json:"gid"`         // the goroutine id which generated this log
	Stack      *Stack  `json:"stack"`       // the stack info of this log
	DebugStack *string `json:"debug_stack"` // the debug stack of this log

	Level  Level         `json:"level"`  // log's level
	Format *string       `json:"format"` // log's format
	Args   []interface{} `json:"args"`   // log's format args
	Fields Fields        `json:"fields"` // additional custom fields
}

Log represent an log, contains all properties.

func NewLog

func NewLog(level Level, pc uintptr, debugStack *string, format *string, args []interface{}, fields Fields) *Log

Create an new Log instance for better performance, caller should be provided by upper

func (*Log) Uptime

func (l *Log) Uptime() int64

Uptime obtain log's createTime relative to application's startTime

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger wrap independent logger

func GetLogger

func GetLogger() *Logger

GetLogger create new Logger by caller's package name

func NewLogger

func NewLogger(name string) *Logger

NewLogger create new Logger by the specified name

func (*Logger) BindFields

func (l *Logger) BindFields(fields Fields)

BindFields add the specified fields into the current Logger.

func (*Logger) Debug

func (l *Logger) Debug(v ...interface{})

Debug record debug level's log

func (*Logger) Debugf

func (l *Logger) Debugf(format string, v ...interface{})

Debugf record debug level's log with custom format.

func (*Logger) Error

func (l *Logger) Error(v ...interface{})

Error record error level's log

func (*Logger) Errorf

func (l *Logger) Errorf(format string, v ...interface{})

Errorf record error level's log with custom format.

func (*Logger) Fatal

func (l *Logger) Fatal(v ...interface{})

Fatal record fatal level's log

func (*Logger) Fatalf

func (l *Logger) Fatalf(format string, v ...interface{})

Fatalf record fatal level's log with custom format.

func (*Logger) Info

func (l *Logger) Info(v ...interface{})

Info record info level's log

func (*Logger) Infof

func (l *Logger) Infof(format string, v ...interface{})

Infof record info level's log with custom format.

func (*Logger) IsDebugEnabled

func (l *Logger) IsDebugEnabled() bool

Whether debug of current logger enabled or not

func (*Logger) IsErrorEnabled

func (l *Logger) IsErrorEnabled() bool

Whether error of current logger enabled or not

func (*Logger) IsFatalEnabled

func (l *Logger) IsFatalEnabled() bool

Whether fatal of current logger enabled or not

func (*Logger) IsInfoEnabled

func (l *Logger) IsInfoEnabled() bool

Whether info of current logger enabled or not

func (*Logger) IsPanicEnabled

func (l *Logger) IsPanicEnabled() bool

Whether panic of current logger enabled or not

func (*Logger) IsTraceEnabled

func (l *Logger) IsTraceEnabled() bool

Whether trace of current logger enabled or not

func (*Logger) IsWarnEnabled

func (l *Logger) IsWarnEnabled() bool

Whether warn of current logger enabled or not

func (*Logger) Level

func (l *Logger) Level() Level

Level obtain logger's level, lower will not be print

func (*Logger) Name

func (l *Logger) Name() string

Name obtain logger's name

func (*Logger) Panic

func (l *Logger) Panic(v ...interface{})

Panic record panic level's log

func (*Logger) Panicf

func (l *Logger) Panicf(format string, v ...interface{})

Panic record panic level's log with custom format

func (*Logger) Trace

func (l *Logger) Trace(v ...interface{})

Trace record trace level's log

func (*Logger) Tracef

func (l *Logger) Tracef(format string, v ...interface{})

Tracef record trace level's log with custom format.

func (*Logger) Warn

func (l *Logger) Warn(v ...interface{})

Warn record warn level's log

func (*Logger) Warnf

func (l *Logger) Warnf(format string, v ...interface{})

Warnf record warn level's log with custom format.

func (*Logger) WithFields

func (l *Logger) WithFields(fields Fields) *Logger

WithFields derive an new Logger by the specified fields from the current Logger.

type Stack

type Stack struct {
	Package  string `json:"package"`
	Filename string `json:"filename"`
	Function string `json:"function"`
	Line     int    `json:"line"`
	// contains filtered or unexported fields
}

Stack represent pc's stack details.

func ParseStack

func ParseStack(pc uintptr) (s *Stack)

ParseStack retrieve pc's stack details, should cache result for performance optimization.

type StdDriver

type StdDriver struct {
	sync.Mutex
}

The default driver, just print stdout directly

func (*StdDriver) GetLevel

func (p *StdDriver) GetLevel(logger string) Level

func (*StdDriver) Name

func (p *StdDriver) Name() string

func (*StdDriver) Print

func (p *StdDriver) Print(l *Log)

Directories

Path Synopsis
custom command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL