log

package module
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Sep 28, 2020 License: MIT Imports: 14 Imported by: 48

README

PkgGoDev Test Coverage Status

Simple Log Framework for Golang (slf4g)

WARNING: This project is still under heavy development. Everything could still change.

Contributing

slf4g is an open source project by echocat. So if you want to make this project even better, you can contribute to this project on Github by fork us.

If you commit code to this project, you have to accept that this code will be released under the license of this project.

License

See the LICENSE file.

Documentation

Index

Constants

View Source 
const RootLoggerName = "ROOT"

RootLoggerName represents the logger which is the root of all other loggers and/or the logger which is used if no name was specified. For example all package log methods (like Info(), Warn(), ...) are using the root logger.

Variables

View Source 
var DefaultLevelProvider = defaultLevelProvider

DefaultLevelProvider is the default instance of a LevelProvider. this could be overwritten for customization purposes.

View Source 
var DefaultLevelProviderFacade = NewLevelProviderFacade(func() LevelProvider {
	return DefaultLevelProvider
})

DefaultLevelProviderFacade always uses the latest reference of DefaultLevelProvider regardless when DefaultLevelProvider was set. This is very useful while initiating Provider and Logger globally where it is hard to guarantees the order how each of these init() methods across the whole project and all of its libraries is called.

Functions

func Debug 

func Debug(args ...interface{})

Debug logs the provided arguments on LevelDebug at the current root Logger.

func Debugf 

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

Debugf is like Debug but wraps the message itself in a fmt.Sprintf action. By contract the actual format action will not be executed before the value will be really consumed.

func Error 

func Error(args ...interface{})

Error logs the provided arguments on LevelError at the current root Logger.

func Errorf 

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

Errorf is like Error but wraps the message itself in a fmt.Sprintf action. By contract the actual format action will not be executed before the value will be really consumed.

func Fatal 

func Fatal(args ...interface{})

Fatal logs the provided arguments on LevelFatal at the current root Logger.

IMPORTANT! In contrast to many other log Golang frameworks this logging Fatal with slf4g does not lead to an os.Exit() by default. By contract the application can do that but it is doing that always GRACEFUL. All processes should be always able to do shutdown operations if needed AND possible.

func Fatalf 

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

Fatalf is like Fatal but wraps the message itself in a fmt.Sprintf action. By contract the actual format action will not be executed before the value will be really consumed.

IMPORTANT! In contrast to many other log Golang frameworks this logging Fatal with slf4g does not lead to an os.Exit() by default. By contract the application can do that but it is doing that always GRACEFUL. All processes should be always able to do shutdown operations if needed AND possible.

func GetErrorOf 

func GetErrorOf(e Event, using Provider) error

GetErrorOf returns for the given Event the contained error (if exists).

func GetLoggerOf 

func GetLoggerOf(e Event, using Provider) *string

GetLoggerOf returns for the given Event the contained logger (name) (if exists).

func GetMessageOf 

func GetMessageOf(e Event, using Provider) *string

GetMessageOf returns for the given Event the contained message (if exists).

func GetTimestampOf 

func GetTimestampOf(e Event, using Provider) *time.Time

GetTimestampOf returns for the given Event the contained timestamp (if exists).

func Info 

func Info(args ...interface{})

Info logs the provided arguments on LevelInfo at the current root Logger.

func Infof 

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

Infof is like Info but wraps the message itself in a fmt.Sprintf action. By contract the actual format action will not be executed before the value will be really consumed.

func IsDebugEnabled 

func IsDebugEnabled() bool

IsDebugEnabled checks if LevelDebug is enabled at the current root Logger.

func IsErrorEnabled 

func IsErrorEnabled() bool

IsErrorEnabled checks if LevelError is enabled at the current root Logger.

func IsFatalEnabled 

func IsFatalEnabled() bool

IsFatalEnabled checks if LevelFatal is enabled at the current root Logger.

func IsInfoEnabled 

func IsInfoEnabled() bool

IsInfoEnabled checks if LevelInfo is enabled at the current root Logger.

func IsLevelEnabled 

func IsLevelEnabled(level Level) bool

IsLevelEnabled checks if the given Level is enabled at the current root Logger.

func IsTraceEnabled 

func IsTraceEnabled() bool

IsTraceEnabled checks if LevelTrace is enabled at the current root Logger.

func IsWarnEnabled 

func IsWarnEnabled() bool

IsWarnEnabled checks if LevelWarn is enabled at the current root Logger.

func SetProvider 

func SetProvider(p Provider)

func Trace 

func Trace(args ...interface{})

Trace logs the provided arguments on LevelTrace at the current root Logger.

func Tracef 

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

Tracef is like Trace but wraps the message itself in a fmt.Sprintf action. By contract the actual format action will not be executed before the value will be really consumed.

func Warn 

func Warn(args ...interface{})

Warn logs the provided arguments on LevelWarn at the current root Logger.

func Warnf 

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

Warnf is like Warn but wraps the message itself in a fmt.Sprintf action. By contract the actual format action will not be executed before the value will be really consumed.

Types

type CoreLogger 

type CoreLogger interface {
	// Log is called to log the given Event. It depends on the implementation
	// if this action will be synchronous or asynchronous.
	Log(Event)

	// IsLevelEnabled returns <true> if the given Level is enabled to be logged
	// with this (Core)Logger.
	IsLevelEnabled(Level) bool

	// GetName returns the name of this (Core)Logger instance. If this is the
	// root logger it will be RootLoggerName.
	GetName() string

	// GetProvider will return the Provider where this (Core)Logger belongs to.
	// This is for example used to access the Levels or fields.KeysSpec used
	// by this (Core)Logger.
	GetProvider() Provider
}

CoreLogger defines the base functions of all Logger of the slf4g framework.

This needs to be usually implemented by loggers that interfaces with the slf4g framework and can be elevated to a full instance of Logger by calling NewLogger().

func UnwrapCore added in v0.3.0 

func UnwrapCore(in CoreLogger) CoreLogger

type Event 

type Event interface {
	// GetLevel returns the Level of this event.
	GetLevel() Level

	// GetCallDepth returns the call depth inside of the call stack that should
	// be ignored before capturing the caller position (if required). This could
	// be increased (if delegating from instance to instance) by calling
	// WithCallDepth().
	GetCallDepth() int

	// GetContext returns an optional context of this event. This is stuff which
	// should not be represented and/or reported and/or could contain hints for
	// the actual logger. Therefore and can be <nil>. This can altered by
	// WithContext().
	GetContext() interface{}

	// GetFields will return all fields which are associated with this Event.
	// This could contain a message, timestamp, error and so on. None of this
	// fields is required to exists by contract. The keys of these fields is
	// defined by Provider.GetFieldKeysSpec(). For example using
	// fields.KeysSpec.GetMessage() it might be possible to get the
	// key of the message.
	GetFields() fields.Fields

	// With returns an variant of this Event with the given key
	// value pair contained inside. If the given key already exists in the
	// current instance this means it will be overwritten.
	With(key string, value interface{}) Event

	// Withf is similar to With but it adds classic fmt.Printf functions to it.
	// It is defined that the format itself will not be executed before the
	// consumption of the value. (See fields.Fields.ForEach() and
	// fields.Fields.Get())
	Withf(key string, format string, args ...interface{}) Event

	// WithAll is similar to With but it can consume more than one field at
	// once. Be aware: There is neither a guarantee that this instance will be
	// copied or not.
	WithAll(map[string]interface{}) Event

	// Without returns a variant of this Event without the given
	// key contained inside. In other words: If someone afterwards tries to
	// call either fields.Fields.ForEach() or fields.Fields.Get() nothing with
	// this key(s) will be returned.
	Without(keys ...string) Event

	// WithCallDepth returns an variant of this Event with the given
	// call depth is added to the existing one of this Event. All other values
	// remaining the same.
	WithCallDepth(int) Event

	// WithContext returns an variant of this Event with the given
	// context is replaced with the existing one of this Event. All other values
	// remaining the same.
	WithContext(ctx interface{}) Event
}

Event represents an event which can be logged using a Logger (or CoreLogger).

Contents

Events are haven dynamic contents (such as messages, errors, ...) provided by GetFields(). Only be contract always provided information are provided by GetLevel() and GetCalDepth().

Immutability

Fields are defined as immutable. Calling the methods With, Withf, WithAll, Without, WithCallDepth and WithContext always results in a new instance of Event that could be either brand new, a copy of the source one or do inherit some stuff of the original called one; but it never modifies the called instance.

func NewEvent 

func NewEvent(level Level, f fields.Fields, callDepth int) Event

NewEvent creates a new instance of Event from the given Level, fields.Fields and the given callDepth.

type Level 

type Level uint16

Level identifies the severity of an event to be logged. As higher ans more important is the event. LevelTrace is the less severe and LevelFatal the most severe.

Customization

Different implementations of Provider could introduce more Levels. All ordinals are unique over all instances of Level. LevelInfo = 3000 will be always LevelInfo = 3000. Another Level which uses the ordinal 3000 can be just assumed as an alias to LevelInfo. Customization only means added new instances of Level. Standard levels always remains available. 

const (
	// LevelTrace defines the lowest possible level. This is usually only used
	// in cases where really detailed logs are required. For example to document
	// the whole communication with a server, including each request with its
	// headers and so on.
	LevelTrace Level = 1000

	// LevelDebug is used to document information which is used to debug
	// problems. These information are in regular operation mode are not
	// required; but could help once enabled to track down common issues.
	LevelDebug Level = 2000

	// LevelInfo is the regular level where everything is logged which is of
	// interest for everybody and should be always visible and imply regular
	// operations of the system. Usually this shows that one operation succeeded
	// successfully; like a user was created.
	LevelInfo Level = 3000

	// LevelWarn implies that something happened which failed but could be
	// recovered gracefully. In best case the user does not noticed anything.
	// But personal should investigate as soon as possible to prevent something
	// like this happening again.
	LevelWarn Level = 4000

	// LevelError implies that something happened which failed and cannot be
	// recovered gracefully but it only affects one or a small amount of users
	// and the rest of the system can continue to work. Personal should
	// investigate right now to prevent such stuff happening again and recover
	// broken users.
	LevelError Level = 5000

	// LevelFatal implies that something happened which failed and cannot be
	// recovered gracefully, which might affect every user of the system. This
	// implies that the whole system is not longer operable and should/will be
	// shutdown (if possible gracefully) right now. Personal is required to
	// investigate right now to prevent such stuff happening again, bring the
	// the system back to operations and recover broken users.
	LevelFatal Level = 6000
)

func (Level) CompareTo 

func (instance Level) CompareTo(o Level) int

CompareTo helps to compare the severity of two levels. It returns how much severe the provided Level is compared to the actual one. Bigger means more severe.

type LevelProvider 

type LevelProvider func() Levels

LevelProvider provides all available Levels.

func NewLevelProviderFacade added in v0.6.0 

func NewLevelProviderFacade(provider func() LevelProvider) LevelProvider

type Levels 

type Levels []Level

Levels represents a slice of 0..n Level.

Additionally it implements the sort.Interface to enable to call sort.Sort to order the contents of this slice by its severity.

func (Levels) Len 

func (instance Levels) Len() int

See sort.Interface

func (Levels) Less 

func (instance Levels) Less(i, j int) bool

See sort.Interface

func (Levels) Swap 

func (instance Levels) Swap(i, j int)

See sort.Interface

type Logger 

type Logger interface {
	CoreLogger

	// Trace logs the provided arguments on LevelTrace with this Logger.
	Trace(...interface{})

	// Tracef is like Trace but wraps the message itself in a fmt.Sprintf action.
	// By contract the actual format action will not be executed before the value
	// will be really consumed.
	Tracef(string, ...interface{})

	// IsTraceEnabled checks if LevelTrace is enabled at this Logger.
	IsTraceEnabled() bool

	// Debug logs the provided arguments on LevelDebug with this Logger.
	Debug(...interface{})

	// Debugf is like Debug but wraps the message itself in a fmt.Sprintf action.
	// By contract the actual format action will not be executed before the value
	// will be really consumed.
	Debugf(string, ...interface{})

	// IsDebugEnabled checks if LevelDebug is enabled at this Logger.
	IsDebugEnabled() bool

	// Info logs the provided arguments on LevelInfo with this Logger.
	Info(...interface{})

	// Infof is like Info but wraps the message itself in a fmt.Sprintf action.
	// By contract the actual format action will not be executed before the value
	// will be really consumed.
	Infof(string, ...interface{})

	// IsInfoEnabled checks if LevelInfo is enabled at this Logger.
	IsInfoEnabled() bool

	// Warn logs the provided arguments on LevelWarn with this Logger.
	Warn(...interface{})

	// Warnf is like Warn but wraps the message itself in a fmt.Sprintf action.
	// By contract the actual format action will not be executed before the value
	// will be really consumed.
	Warnf(string, ...interface{})

	// IsWarnEnabled checks if LevelWarn is enabled at this Logger.
	IsWarnEnabled() bool

	// Error logs the provided arguments on LevelError with this Logger.
	Error(...interface{})

	// Errorf is like Error but wraps the message itself in a fmt.Sprintf action.
	// By contract the actual format action will not be executed before the value
	// will be really consumed.
	Errorf(string, ...interface{})

	// IsErrorEnabled checks if LevelError is enabled at this Logger.
	IsErrorEnabled() bool

	// Fatal logs the provided arguments on LevelFatal with this Logger.
	//
	// IMPORTANT! In contrast to many other log Golang frameworks this logging Fatal
	// with slf4g does not lead to an os.Exit() by default. By contract the
	// application can do that but it is doing that always GRACEFUL. All processes
	// should be always able to do shutdown operations if needed AND possible.
	Fatal(...interface{})

	// Fatalf is like Fatal but wraps the message itself in a fmt.Sprintf action.
	// By contract the actual format action will not be executed before the value
	// will be really consumed.
	//
	// IMPORTANT! In contrast to many other log Golang frameworks this logging Fatal
	// with slf4g does not lead to an os.Exit() by default. By contract the
	// application can do that but it is doing that always GRACEFUL. All processes
	// should be always able to do shutdown operations if needed AND possible.
	Fatalf(string, ...interface{})

	// IsFatalEnabled checks if LevelFatal is enabled at this Logger.
	IsFatalEnabled() bool

	// With returns an variant of this Logger with the given key
	// value pair contained inside. If the given key already exists in the
	// current instance this means it will be overwritten.
	With(name string, value interface{}) Logger

	// Withf is similar to With but it adds classic fmt.Printf functions to it.
	// It is defined that the format itself will not be executed before the
	// consumption of the value.
	Withf(name string, format string, args ...interface{}) Logger

	// WithError is similar to With but it adds an error as field.
	WithError(error) Logger

	// WithAll is similar to With but it can consume more than one field at
	// once. Be aware: There is neither a guarantee that this instance will be
	// copied or not.
	WithAll(map[string]interface{}) Logger

	// Without returns a variant of this Logger without the given
	// key contained inside. In other words: If someone afterwards tries to
	// call either ForEach() or Get() nothing with this key(s) will be returned.
	Without(keys ...string) Logger
}

Logger defines an instance which executes log event actions.

func GetLogger 

func GetLogger(name string) Logger

GetLogger returns a logger for the given name from the global Provider.

func GetRootLogger added in v0.6.0 

func GetRootLogger() Logger

GetLogger returns the ROOT logger from the global Provider.

func NewLogger 

func NewLogger(cl CoreLogger) Logger

func NewLoggerFacade added in v0.3.0 

func NewLoggerFacade(provider func() CoreLogger) Logger

func Unwrap added in v0.2.0 

func Unwrap(in Logger) Logger

func With 

func With(name string, value interface{}) Logger

With returns a root Logger which will contain the provided field.

func WithAll added in v0.5.5 

func WithAll(of map[string]interface{}) Logger

WithAll is similar to With but it can consume more than one field at once. Be aware: There is neither a guarantee that this instance will be copied or not.

func WithError 

func WithError(err error) Logger

WithError is similar to With but it adds specially an error field.

func Withf added in v0.1.3 

func Withf(name string, format string, args ...interface{}) Logger

Withf is similar to With but it adds classic fmt.Printf functions to it. It is defined that the format itself will not be executed before the consumption of the value.

type LoggerFactory added in v0.4.0 

type LoggerFactory func(name string) Logger

type LoggerProvider added in v0.6.0 

type LoggerProvider interface {
	GetLogger(name string) Logger
}

func NewLoggerCache added in v0.4.0 

func NewLoggerCache(factory LoggerFactory) LoggerProvider

type LoggingWriter added in v0.3.0 

type LoggingWriter struct {
	CoreLogger
	LogAs Level
}

func (*LoggingWriter) Write added in v0.3.0 

func (instance *LoggingWriter) Write(p []byte) (n int, err error)

type Provider 

type Provider interface {
	GetLogger(name string) Logger
	GetName() string
	GetAllLevels() Levels
	GetFieldKeysSpec() fields.KeysSpec
}

func AllProviders 

func AllProviders() []Provider

func GetProvider 

func GetProvider() Provider

func NewProviderFacade added in v0.3.0 

func NewProviderFacade(provider func() Provider) Provider

func RegisterProvider 

func RegisterProvider(p Provider) Provider

func UnregisterProvider 

func UnregisterProvider(name string) Provider

func UnwrapProvider added in v0.2.0 

func UnwrapProvider(in Provider) Provider

Source Files

View all Source files

Directories

Path Synopsis
Fields represents a collection of key value pairs.
 Fields represents a collection of key value pairs.
internal
demo
test/assert
native module
std
bridge
bridge/hook

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.