lork

package module
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2022 License: Apache-2.0 Imports: 23 Imported by: 7

README

lork

The flexible, extensible and structured logging for Go. Lork provides bridge and binder for logger which can send log from logger to another logger you preferred. Lork also provides unified writers, encoders and filters, it brings different logger with same apis and flexible configurations.

Install

Add the following to your go.mod

require (
	github.com/coolerfall/lork v0.6.1
)

Quick Start

  • Configure the output writer:
lork.Logger().AddWriter(lork.NewConsoleWriter(func(o *lork.ConsoleWriterOption) {
    o.Encoder = lork.NewPatternEncoder(func(opt *lork.PatternEncoderOption) {
        opt.Pattern = "#color(#date{2006-01-02T15:04:05.000Z07:00}){cyan} #color(" +
"#level) #color([#logger{32}]){magenta} : #message #fields"
    })
}))
fw := lork.NewFileWriter(func(o *lork.FileWriterOption) {
    o.Encoder = lork.NewJsonEncoder()
    o.Filter = lork.NewThresholdFilter(lork.DebugLevel)
    o.Filename = "example/lork-test.log"
    o.RollingPolicy = lork.NewSizeAndTimeBasedRollingPolicy(
        func(o *lork.SizeAndTimeBasedRPOption) {
            o.FilenamePattern = "example/lork-archive.#date{2006-01-02}.#index.log"
            o.MaxFileSize = "10MB"
            o.MaxHistory = 10
    })
})
aw := lork.NewAsyncWriter(func(o *lork.AsyncWriterOption) {
    o.RefWriter = fw
})
lork.Logger().AddWriter(aw)
  • Add logging:
lork.Logger().Trace().Msg("lork")
lork.Logger().Info().Int("int", 88).Any("lork", "val").Msge()
  • If you log with other logger, it will send to the bound logger:
lork.Install(lork.NewLogBridge())
lork.Install(bridge.NewZapBrige())

zap.L().With().Warn("this is zap")
log.Printf("this is builtin logger")

Note: only global logger will send log to bound logger if using logger like zap, zerolog, logrus or other loggers.

Configuration

The following shows all the configurations of lork.

Writer

Lork provides several writers for logging, and it supports to add multiple writers.

Console Writer

This writer sends the logs to Stdout console. It supports the following options:

  • Encoder, encoder of logs
  • Filter, filter of logs
File Writer

It supports the following options:

  • Encoder, encoder of logs
  • Filter, filter of logs
  • Filename, the filename of the log file to write
  • RollingPolicy, the policy to roll over log files. Lork providesTimeBasedPpolicy and SizeAndTimeBasedPolicy
Asynchronous Writer

This writer wraps Console Writer or File Writer to write log in background. It supports the following options:

  • RefWriter, the referenced writer.
  • QueueSize, the size of the blocking queue.
Socket Writer

This writer sends logs to remote server via socket. It supports the following options:

  • RemoteUrl, url of remote server
  • QueueSize, the size of queue
  • ReconnectionDelay, delay milliseconds when reconnecting server
  • Filter, filters of logs

The server should start Socket Readerto receive logs, and it supports the following options:

  • Path, the path of the url
  • Port, the port of this server will listen
Syslog Writer

This writer is an implementation for syslog. It supports the following options:

  • Tag, the tag of syslog.
  • Address, address of syslog server
  • Network, network of syslog server, see net.Dial
  • Filter, filters of logs

Encoder

Lork provides some builtin encoders which can be configured in writers.

Pattern Encoder

Encode logs with custom pattern format layout, for example:

#color(#date{2006-01-02T15:04:05.000Z07:00}){cyan} #color(#level) #color([#logger{16}]){magenta} : #message #fields
color

This pattern adds specified color the content. This only works in console writer.

#color(theContent){colorValue}

Normal colors supported: black, red, green, yellow, blue, magenta, cyan, white Bright colors supported: blackbr, redbr, greenbr, yellowbr, bluebr, magentabr, cyanbr, whitebr

level

This pattern adds level information in logs.

#level
logger

This pattern adds logger name in logs.

#logger{length}
message

This pattern adds message in logs.

#message
fields

This pattern adds key-value fields in logs.

#fields
Json Encoder

Encode logs with json format.

Filter

Filters can filter unused logs from origin logs. Lork provides some built in filters.

Threshold Filter

This filter will deny all logs which is lower than the level set.

Keyword Filter

A simple keyword filter which matches the specified keyword.

Benchmarks

Benchmarks with complex log field, different encoder and writer.

cpu: Intel(R) Core(TM) i7-8550U CPU @ 1.80GHz
BenchmarkJsonFileWriter-8      	  250128        5290 ns/op      0 B/op      0 allocs/op
BenchmarkPatternFileWriter-8   	  313402        3777 ns/op      0 B/op      0 allocs/op
BenchmarkAsyncFileWriter-8     	 1107603        1060 ns/op      0 B/op      0 allocs/op
BenchmarkNoWriter-8            	 1441761        843.5 ns/op     0 B/op      0 allocs/op

Credits

  • slf4j: Simple Logging Facade for Java
  • logback: The reliable, generic, fast and flexible logging framework for Java.

Supports

If you enjoy this project and want to support it, you can buy a coffee.

Buy Me A Coffee

License

Copyright (c) 2019-2022 Vincent Cheung (coolingfall@gmail.com).

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Documentation

Index

Constants

View Source 
const (
	LevelFieldKey     = "level"
	TimestampFieldKey = "time"
	MessageFieldKey   = "message"
	LoggerFieldKey    = "logger_name"
	ErrorFieldKey     = "error"

	TimestampFormat   = time.RFC3339Nano
	TimeFormatRFC3339 = "2006-01-02T15:04:05.000Z07:00"

	RootLoggerName = "ROOT"
)
View Source 
const (
	DefaultPattern = "#color(#date{2006-01-02T15:04:05.000Z07:00}){cyan} #color(#level) : #message #fields"
)

Variables

This section is empty.

Functions

func Bind 

func Bind(logger ILogger)

Bind binds an implementation of lork logger as output logger.

func BridgeWrite 

func BridgeWrite(bridge Bridge, p []byte) error

BridgeWrite writes data from bridge to lork logger.

func Install 

func Install(bridge Bridge)

Install installs a logging framework bridge into lork. All the log of the bridge will be delegated to lork if the logging framework bridge was installed.

func NewBlockingQueue 

func NewBlockingQueue(capacity int) *blockingQueue

NewBlockingQueue creates a new blocking queue.

func NewLogBridge 

func NewLogBridge() *logBridge

NewLogBridge creates a new lork bridge for standard log.

func NewPatternCompiler 

func NewPatternCompiler(node *node, converterMap map[string]NewConverter) *patternCompiler

NewPatternCompiler creates a new instance of pattern compiler.

func NewPatternParser 

func NewPatternParser(pattern string) *patternParser

NewPatternParser creates a new instance of pattern parser.

func PackageName 

func PackageName(skip int) string

PackageName get the package name of caller.

func ReplaceJson 

func ReplaceJson(p []byte, buf *bytes.Buffer, searchKey string,
	transform func(k, v []byte) (nk, kv []byte, e error)) error

ReplaceJson replaces key/value with given search key.

func Report 

func Report(msg string)

Report reports message in stdout

func Reportf 

func Reportf(format string, args ...interface{})

Reportf reports message with arguments in stdout

func ReportfExit 

func ReportfExit(format string, args ...interface{})

ReportfExit reports message with arguments in stdout and exit process.

Types

type ArchiveRemover 

type ArchiveRemover interface {
	// MaxHistory sets max history for logs.
	MaxHistory(max int)

	// CleanAsync cleans logs asynchronously with given time.
	CleanAsync(now time.Time)
}

ArchiveRemover represents a remover which removes archived logs.

type Archiver 

type Archiver interface {
	// Archive makes an archiver with given filename and archive filename.
	Archive(filename, archiveFilename string) error
}

type AsyncWriterOption 

type AsyncWriterOption struct {
	RefWriter Writer
	QueueSize int
}

AsyncWriterOption represents available options for async writer.

type Bridge 

type Bridge interface {
	// Name returns the name of this bridge.
	Name() string

	// ParseLevel parses the given level string into lork level.
	ParseLevel(lvl string) Level
}

Bridge represents bridge between other logging framework and lork logger.

type ConsoleWriterOption 

type ConsoleWriterOption struct {
	Encoder Encoder
	Filter  Filter
}

ConsoleWriterOption represents available options for console writer.

type Converter 

type Converter interface {
	// AttachNext attaches next converter to the chain.
	AttachNext(next Converter)

	// Next will get next converter from the chain.
	Next() Converter

	// AttachChild attaches child converter to current converter.
	AttachChild(child Converter)

	// AttachOptions attaches options to current converter.
	AttachOptions(opts []string)

	// Convert converts given data into buffer.
	Convert(origin interface{}, buf *bytes.Buffer)
}

Converter represents a pattern converter which will convert pattern to string.

func NewLiteralConverter 

func NewLiteralConverter(value string) Converter

type Encoder 

type Encoder interface {
	// Encode encodes origin data to formatted data.
	Encode(e *LogEvent) (data []byte, err error)
}

Encoder represents an encoder to encode logging event into different format.

func NewJsonEncoder 

func NewJsonEncoder() Encoder

NewJsonEncoder creates a new instance of encoder to encode data to json.

func NewPatternEncoder 

func NewPatternEncoder(options ...func(*PatternEncoderOption)) Encoder

NewPatternEncoder creates a new instance of pattern encoder.

type EventWriter 

type EventWriter interface {
	// WriteEvent writes LogEvent.
	WriteEvent(event *LogEvent) (n int, err error)
}

EventWriter represents writer which will write raw LogEvent.

type FileWriterOption 

type FileWriterOption struct {
	Encoder       Encoder
	Filter        Filter
	RollingPolicy RollingPolicy
	Filename      string
}

FileWriterOption represents available options for file writer.

type Filter 

type Filter interface {
	// Do filters the logging. The logs will be accepted or denied according to FilterReply.
	Do(e *LogEvent) FilterReply
}

Filter represents a logging filter for lork.

func NewKeywordFilter 

func NewKeywordFilter(keywords ...string) Filter

NewKeywordFilter creates a new instance of keywordFilter.

func NewThresholdFilter 

func NewThresholdFilter(lvl Level) Filter

NewThresholdFilter creates a new instance of thresholdFilter.

type FilterReply 

type FilterReply int8

FilterReply defines the result of filter. 

const (
	// Accept represents the logging will be accepted by filter.
	Accept FilterReply = iota + 1
	// Deny represents the logging will be denied by filter.
	Deny
)

type ILogger 

type ILogger interface {
	// Name returns the name of current lork logger implementation.
	Name() string

	// AddWriter add one or more writer to this logger.
	AddWriter(w ...Writer)

	// ResetWriter will remove all writers added before.
	ResetWriter()

	// SetLevel sets global level for logger.
	SetLevel(lvl Level)

	// Trace logs with trace level.
	Trace() Record

	// Debug logs with debug level.
	Debug() Record

	// Info logs with info level.
	Info() Record

	// Warn logs with warn level.
	Warn() Record

	// Error logs with error level.
	Error() Record

	// Fatal logs with fatal level.
	Fatal() Record

	// Panic logs with panic level.
	Panic() Record

	// Level logs with specified level.
	Level(lvl Level) Record

	// WriteEvent writes raw logging event.
	WriteEvent(e *LogEvent)
}

ILogger represents lork logging interface definition.

func Logger 

func Logger(name ...string) ILogger

Logger get a global lork logger to use. The name will only get the first one.

func LoggerC 

func LoggerC() ILogger

LoggerC get a global lork logger with a caller package name. Note: this will call runtime.Caller function.

func NewClassicLogger 

func NewClassicLogger() ILogger

type Level 

type Level int8
const (
	TraceLevel Level = iota
	DebugLevel
	InfoLevel
	WarnLevel
	ErrorLevel
	FatalLevel
	PanicLevel
)

func ParseLevel 

func ParseLevel(lvl string) Level

ParseLevel converts a level string into lork level value.

func (Level) String 

func (l Level) String() string

type Lifecycle 

type Lifecycle interface {
	// Start the component.
	Start()
	// Stop the component.
	Stop()
}

Lifecycle represents the lifecycle of component.

type LogEvent 

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

func MakeEvent 

func MakeEvent(p []byte) *LogEvent

func NewLogEvent 

func NewLogEvent() *LogEvent

NewLogEvent gets a LogEvent from pool.

func (*LogEvent) Copy 

func (e *LogEvent) Copy() *LogEvent

func (*LogEvent) Fields 

func (e *LogEvent) Fields(callback func(k, v []byte, isString bool) error) error

Fields gets extra key and value bytes.

func (*LogEvent) Level 

func (e *LogEvent) Level() []byte

Level returns level string bytes.

func (*LogEvent) LevelInt 

func (e *LogEvent) LevelInt() Level

LevelInt returns level int value.

func (*LogEvent) Logger 

func (e *LogEvent) Logger() []byte

Logger return logger name bytes.

func (*LogEvent) Message 

func (e *LogEvent) Message() []byte

Message returns message bytes.

func (*LogEvent) Recycle 

func (e *LogEvent) Recycle()

func (*LogEvent) Time 

func (e *LogEvent) Time() []byte

Time returns rfc3339nano bytes.

type MultiWriter 

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

MultiWriter represents multiple writer which implements lork.Writer. This writer is used as output which will implement ILogger.

func NewMultiWriter 

func NewMultiWriter() *MultiWriter

NewMultiWriter creates a new multiple writer.

func (*MultiWriter) AddWriter 

func (mw *MultiWriter) AddWriter(writers ...Writer)

AddWriter adds a lork writer into multi writer.

func (*MultiWriter) Reset 

func (mw *MultiWriter) Reset()

Reset will remove all writers.

func (*MultiWriter) Write 

func (mw *MultiWriter) Write(p []byte) (n int, err error)

func (*MultiWriter) WriteEvent 

func (mw *MultiWriter) WriteEvent(event *LogEvent) (n int, err error)

type NewConverter 

type NewConverter func() Converter

type PatternEncoderOption 

type PatternEncoderOption struct {
	Pattern    string
	Converters map[string]NewConverter
}

type Record 

type Record interface {
	// Str adds string value to this record.
	Str(key, val string) Record

	// Strs adds string array value to this record.
	Strs(key string, val []string) Record

	// Bytes adds byte array value to this record.
	Bytes(key string, val []byte) Record

	// Err adds err to this record.
	Err(err error) Record

	// Errs adds err array to this record.
	Errs(key string, errs []error) Record

	// Bool adds bool value to this record.
	Bool(key string, val bool) Record

	// Bools adds bool array value to this record.
	Bools(key string, val []bool) Record

	// Int adds int value to this record.
	Int(key string, val int) Record

	// Ints adds int array value to this record.
	Ints(key string, val []int) Record

	// Int8 adds int8 value to this record.
	Int8(key string, val int8) Record

	// Ints8 adds int8 array value to this record.
	Ints8(key string, val []int8) Record

	// Int16 adds int16 value to this record.
	Int16(key string, val int16) Record

	// Ints16 adds int16 array value to this record.
	Ints16(key string, val []int16) Record

	// Int32 adds int32 value to this record.
	Int32(key string, val int32) Record

	// Ints32 adds int32 array value to this record.
	Ints32(key string, val []int32) Record

	// Int64 adds int64 value to this record.
	Int64(key string, val int64) Record

	// Ints64 adds int64 array value to this record.
	Ints64(key string, val []int64) Record

	// Uint adds uint value to this record.
	Uint(key string, val uint) Record

	// Uints adds uint array value to this record.
	Uints(key string, val []uint) Record

	// Uint8 adds uint8 value to this record.
	Uint8(key string, val uint8) Record

	// Uints8 adds uint8 array value to this record.
	Uints8(key string, val []uint8) Record

	// Uint16 adds uint16 value to this record.
	Uint16(key string, val uint16) Record

	// Uints16 adds uint16 array value to this record.
	Uints16(key string, val []uint16) Record

	// Uint32 adds uint32 value to this record.
	Uint32(key string, val uint32) Record

	// Uints32 adds uint32 array value to this record.
	Uints32(key string, val []uint32) Record

	// Uint64 adds uint64 value to this record.
	Uint64(key string, val uint64) Record

	// Uints64 adds uint64 array value to this record.
	Uints64(key string, val []uint64) Record

	// Float32 adds float32 value to this record.
	Float32(key string, val float32) Record

	// Floats32 adds float32 array value to this record.
	Floats32(key string, val []float32) Record

	// Float64 adds float64 value to this record.
	Float64(key string, val float64) Record

	// Floats64 adds float64 array value to this record.
	Floats64(key string, val []float64) Record

	// Time adds time value to this record.
	Time(key string, val time.Time) Record

	// Times adds time array value to this record.
	Times(key string, val []time.Time) Record

	// Dur adds duration value to this record.
	Dur(key string, val time.Duration) Record

	// Durs adds duration array value to this record.
	Durs(key string, val []time.Duration) Record

	// Any adds any value to this record.
	Any(key string, val interface{}) Record

	// Msge outputs log without message
	Msge()

	// Msg adds a message to this record and output log.
	Msg(msg string)

	// Msgf adds a message with format to this record and output log.
	Msgf(format string, v ...interface{})
}

Record represents a log record to hold the data to log.

type RollingPolicy 

type RollingPolicy interface {
	// Prepare prepares current rolling policy
	Prepare() error

	// Attach attaches file writer.
	Attach(w *fileWriter)

	// ShouldTrigger check if there's necessary to trigger rolling.
	ShouldTrigger(fileSize int64) bool

	// Rotate does the log rolling.
	Rotate() error
}

RollingPolicy represents policy for log rolling.

func NewNoopRollingPolicy 

func NewNoopRollingPolicy() RollingPolicy

NewNoopRollingPolicy creates a new instance of noop rolling policy which will do nothing.

func NewSizeAndTimeBasedRollingPolicy 

func NewSizeAndTimeBasedRollingPolicy(options ...func(
	*SizeAndTimeBasedRPOption)) RollingPolicy

NewSizeAndTimeBasedRollingPolicy creates a new instance of size and time based rolling policy for file writer.

func NewTimeBasedRollingPolicy 

func NewTimeBasedRollingPolicy(options ...func(*TimeBasedRPOption)) RollingPolicy

NewTimeBasedRollingPolicy creates an instance of time based rolling policy for file writer.

type SizeAndTimeBasedRPOption 

type SizeAndTimeBasedRPOption struct {
	FilenamePattern string
	MaxFileSize     string
	MaxHistory      int
}

SizeAndTimeBasedRPOption represents available options for size and time based rolling policy.

type SocketReader 

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

func NewSocketReader 

func NewSocketReader(options ...func(*SocketReaderOption)) *SocketReader

NewSocketReader creates a new instance of socket reader.

func (*SocketReader) Start 

func (sr *SocketReader) Start()

func (*SocketReader) Stop 

func (sr *SocketReader) Stop()

type SocketReaderOption 

type SocketReaderOption struct {
	Path string
	Port int
}

type SocketWriterOption 

type SocketWriterOption struct {
	RemoteUrl         *url.URL
	QueueSize         int
	ReconnectionDelay time.Duration
	Filter            Filter
}

type SyslogWriterOption added in v0.6.1 

type SyslogWriterOption struct {
	Tag string
	// See net.Dial
	Address, Network string
	Filter           Filter
	// contains filtered or unexported fields
}

type TimeBasedRPOption 

type TimeBasedRPOption struct {
	FilenamePattern string
	MaxHistory      int
}

TimeBasedRPOption represents available options for size and time based rolling policy.

type Writer 

type Writer interface {
	io.Writer

	// Encoder returns encoder used in current writer.
	Encoder() Encoder

	// Filter returns filter used in current writer.
	Filter() Filter
}

Writer is the interface that wraps the io.Writer, adds Encoder and Filter func for logger to encode and filter logs.

func NewAsyncWriter 

func NewAsyncWriter(options ...func(*AsyncWriterOption)) Writer

NewAsyncWriter creates a new instance of asynchronous writer.

func NewConsoleWriter 

func NewConsoleWriter(options ...func(*ConsoleWriterOption)) Writer

NewConsoleWriter creates a new instance of console writer.

func NewFileWriter 

func NewFileWriter(options ...func(*FileWriterOption)) Writer

NewFileWriter creates a new instance of file writer.

func NewSocketWriter 

func NewSocketWriter(options ...func(*SocketWriterOption)) Writer

NewSocketWriter create a logging writer via socket.

func NewSyslogWriter added in v0.6.1 

func NewSyslogWriter(options ...func(option *SyslogWriterOption)) Writer

NewSyslogWriter create a logging writer via syslog.

Source Files

View all Source files

Directories

Path Synopsis
bind
logrus Module
zap Module
zero Module
bridge module
example module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.