logger

package module
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Jan 14, 2022 License: MIT Imports: 14 Imported by: 1

README

Fast levelled logging package with customizable formatting.

Supports logging in 2 modes:

  • no locks, fastest possible logging, no guarantees for io.Writer thread safety
  • mutex locks during writes, still far faster than standard library logger

Running without locks isn't likely to cause you any issues*, but if it does, you can wrap your io.Writer using AddSafety() when instantiating your new Logger. Even when running the benchmarks, this library has no printing issues without locks, so in most cases you'll be fine, but the safety is there if you need it.

*most logging libraries advertising high speeds are likely not performing mutex locks, which is why with this library you have the option to opt-in/out of them.

Note there are 2 uses of the unsafe package:

  • safer interface nil value checks, uses similar logic to reflect package to check if the value in the internal fat pointer is nil
  • casting a byte slice to string to allow sharing of similar byte and string methods, performs same logic as strings.Builder{}.String()

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultTextFormat = TextFormat{
	Strict:   false,
	Verbose:  false,
	MaxDepth: 10,
	Levels:   DefaultLevels(),
}

DefaultTextFormat is the default TextFormat instance

Functions

func AddSafety added in v1.1.3 

func AddSafety(w io.Writer) io.Writer

AddSafety wraps an io.Writer to provide mutex locking protection

func Debug 

func Debug(a ...interface{})

Debug prints the provided arguments with the debug prefix to the global Logger instance.

func Debugf 

func Debugf(s string, a ...interface{})

Debugf prints the provided format string and arguments with the debug prefix to the global Logger instance.

func Error 

func Error(a ...interface{})

Error prints the provided arguments with the error prefix to the global Logger instance.

func Errorf 

func Errorf(s string, a ...interface{})

Errorf prints the provided format string and arguments with the error prefix to the global Logger instance.

func Fatal 

func Fatal(a ...interface{})

Fatal prints the provided arguments with the fatal prefix to the global Logger instance before exiting the program with os.Exit(1).

func Fatalf 

func Fatalf(s string, a ...interface{})

Fatalf prints the provided format string and arguments with the fatal prefix to the global Logger instance before exiting the program with os.Exit(1).

func Info 

func Info(a ...interface{})

Info prints the provided arguments with the info prefix to the global Logger instance.

func Infof 

func Infof(s string, a ...interface{})

Infof prints the provided format string and arguments with the info prefix to the global Logger instance.

func Log 

func Log(lvl LEVEL, a ...interface{})

Log prints the provided arguments with the supplied log level to the global Logger instance.

func Logf 

func Logf(lvl LEVEL, s string, a ...interface{})

Logf prints the provided format string and arguments with the supplied log level to the global Logger instance.

func Print 

func Print(a ...interface{})

Print simply prints provided arguments to the global Logger instance.

func Printf 

func Printf(s string, a ...interface{})

Printf simply prints provided the provided format string and arguments to the global Logger instance.

func Warn 

func Warn(a ...interface{})

Warn prints the provided arguments with the warn prefix to the global Logger instance.

func Warnf 

func Warnf(s string, a ...interface{})

Warnf prints the provided format string and arguments with the warn prefix to the global Logger instance.

Types

type Entry 

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

Entry defines an entry in the log, it is NOT safe for concurrent use.

func (*Entry) Append added in v1.2.5 

func (e *Entry) Append(a ...interface{}) *Entry

Append will append the given args formatted using fmt.Sprint(a...) to the Entry.

func (*Entry) Appendf added in v1.2.5 

func (e *Entry) Appendf(s string, a ...interface{}) *Entry

Appendf will append the given format string and args using fmt.Sprintf(s, a...) to the Entry.

func (*Entry) Context 

func (e *Entry) Context() context.Context

Context returns the current set Entry context.Context.

func (*Entry) Fields 

func (e *Entry) Fields(kv ...KV) *Entry

Fields appends a map of key-value pairs to the log entry, these are formatted using the `go-format` library and the key / value format directives.

func (*Entry) Hooks 

func (e *Entry) Hooks() *Entry

Hooks applies currently set Hooks to the Entry. Please note this CAN be called and perform the Hooks multiple times.

func (*Entry) Level 

func (e *Entry) Level(lvl LEVEL) *Entry

Level appends the supplied level to the log entry, and sets the entry level. Please note this CAN be called and append log levels multiple times.

func (*Entry) Msg 

func (e *Entry) Msg(a ...interface{})

Msg appends the fmt.Sprint() formatted final message to the log and calls .Send()

func (*Entry) Msgf 

func (e *Entry) Msgf(s string, a ...interface{})

Msgf appends the fmt.Sprintf() formatted final message to the log and calls .Send()

func (*Entry) Send 

func (e *Entry) Send()

Send triggers write of the log entry, skipping if the entry's log LEVEL is below the currently set Logger level, and releases the Entry back to the Logger's Entry pool. So it is NOT safe to continue using this Entry object after calling .Send(), .Msg() or .Msgf()

func (*Entry) Timestamp 

func (e *Entry) Timestamp() *Entry

Timestamp appends the current timestamp to the log entry. Please note this CAN be called and append the timestamp multiple times.

func (*Entry) TimestampIf 

func (e *Entry) TimestampIf() *Entry

TimestampIf performs Entry.Timestamp() only IF timestamping is enabled for the Logger. Please note this CAN be called multiple times.

func (*Entry) WithContext 

func (e *Entry) WithContext(ctx context.Context) *Entry

WithContext updates Entry context value to the supplied.

type Formatter added in v1.4.0 

type Formatter interface {
	Append(*format.Buffer, ...interface{})
	Appendf(*format.Buffer, string, ...interface{})
}

Formatter represents a means of print formatted values and format strings to an io.Writer.

func Fmt added in v1.4.0 

func Fmt() Formatter

Fmt returns a `fmt` (from the std library) based Formatter instance.

func Format added in v1.4.0 

func Format() Formatter

Format returns a `go-format` based Formatter instance, please note this uses Rust-style printf formatting directives and will not be compatible with existing format statements.

type Hook 

type Hook interface {
	Do(*Entry)
}

Hook defines a log Entry modifier

type HookFunc 

type HookFunc func(*Entry)

HookFunc is a simple adapter to allow functions to satisfy the Hook interface

func (HookFunc) Do 

func (hook HookFunc) Do(entry *Entry)

type KV added in v1.4.0 

type KV struct {
	K string
	V interface{}
}

KV represents the key-value.

type LEVEL 

type LEVEL uint8

LEVEL defines a level of logging 

const (
	DEBUG LEVEL = 5
	INFO  LEVEL = 10
	WARN  LEVEL = 15
	ERROR LEVEL = 20
	FATAL LEVEL = 25
)

Available levels of logging.

type Levels 

type Levels [^LEVEL(0)]string

Levels defines a mapping of log LEVELs to formatted level strings

func DefaultLevels 

func DefaultLevels() Levels

DefaultLevels returns the default set of log levels

func (Levels) Get added in v1.3.1 

func (l Levels) Get(lvl LEVEL) string

Get fetches the level string for the provided value, or "unknown"

type Logger 

type Logger struct {
	// Hooks defines a list of hooks which can be called on each
	// Entry using the .Hooks() receiver.
	Hooks []Hook

	// Format allows specifying the underlying formatting
	// method/library used.
	Format Formatter

	// Levels defines currently set mappings of available log levels
	// to their string representation.
	Levels Levels

	// Timestamp defines whether to automatically append timestamps
	// to entries written via Logger convience methods and specifically
	// Entry.TimestampIf().
	Timestamp bool

	// Level is the current log LEVEL, entries at level below the
	// currently set level will not be output.
	Level LEVEL

	// BufferSize is the Entry buffer size to use when allocating
	// new Entry objects. This should be modified atomically.
	BufSize int64

	// Output is the log's output writer.
	Output io.Writer
	// contains filtered or unexported fields
}

func Default 

func Default() *Logger

Default returns the default Logger instance.

func New 

func New(out io.Writer) *Logger

New returns a new Logger instance with defaults

func NewWith 

func NewWith(lvl LEVEL, timestamp bool, fmt Formatter, bufsize int64, out io.Writer) *Logger

NewWith returns a new Logger instance with supplied configuration

func (*Logger) Debug 

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

Debug prints the provided arguments with the debug prefix

func (*Logger) Debugf 

func (l *Logger) Debugf(s string, a ...interface{})

Debugf prints the provided format string and arguments with the debug prefix

func (*Logger) Entry 

func (l *Logger) Entry() *Entry

Entry returns a new Entry from the Logger's pool with background context

func (*Logger) Error 

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

Error prints the provided arguments with the error prefix

func (*Logger) Errorf 

func (l *Logger) Errorf(s string, a ...interface{})

Errorf prints the provided format string and arguments with the error prefix

func (*Logger) Fatal 

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

Fatal prints provided arguments with the fatal prefix before exiting the program with os.Exit(1)

func (*Logger) Fatalf 

func (l *Logger) Fatalf(s string, a ...interface{})

Fatalf prints provided the provided format string and arguments with the fatal prefix before exiting the program with os.Exit(1)

func (*Logger) Info 

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

Info prints the provided arguments with the info prefix

func (*Logger) Infof 

func (l *Logger) Infof(s string, a ...interface{})

Infof prints the provided format string and arguments with the info prefix

func (*Logger) Log 

func (l *Logger) Log(lvl LEVEL, a ...interface{})

Log prints the provided arguments at the supplied log level

func (*Logger) Logf 

func (l *Logger) Logf(lvl LEVEL, s string, a ...interface{})

Logf prints the provided format string and arguments at the supplied log level

func (*Logger) Print 

func (l *Logger) Print(a ...interface{})

Print simply prints provided arguments

func (*Logger) Printf 

func (l *Logger) Printf(s string, a ...interface{})

Printf simply prints provided the provided format string and arguments

func (*Logger) Warn 

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

Warn prints the provided arguments with the warn prefix

func (*Logger) Warnf 

func (l *Logger) Warnf(s string, a ...interface{})

Warnf prints the provided format string and arguments with the warn prefix

type TextFormat 

type TextFormat struct {
	// Strict defines whether to use strict key-value pair formatting, i.e. should the level
	// timestamp and msg be formatted as key-value pairs (with forced quoting for msg)
	Strict bool

	// Verbose defines whether to increase output verbosity, i.e. include types with nil values
	// and force values implementing .String() / .AppendFormat() to be printed as a struct etc.
	Verbose bool

	// MaxDepth specifies the max depth of fields the formatter will iterate
	MaxDepth uint8

	// Levels defines the map of log LEVELs to level strings
	Levels Levels
}

TextFormat is the default LogFormat implementation, with very similar formatting to the standard "fmt" package's '%#v' operator. The main difference being that pointers are dereferenced as far as possible in order to reach a printable value. It is also *mildly* faster.

func (TextFormat) AppendBool added in v1.3.0 

func (f TextFormat) AppendBool(buf *bytes.Buffer, value bool)

func (TextFormat) AppendBools added in v1.3.0 

func (f TextFormat) AppendBools(buf *bytes.Buffer, value []bool)

func (TextFormat) AppendByte added in v1.3.0 

func (f TextFormat) AppendByte(buf *bytes.Buffer, value byte)

func (TextFormat) AppendBytes added in v1.3.0 

func (f TextFormat) AppendBytes(buf *bytes.Buffer, value []byte)

func (TextFormat) AppendDuration added in v1.3.0 

func (f TextFormat) AppendDuration(buf *bytes.Buffer, value time.Duration)

func (TextFormat) AppendDurations added in v1.3.0 

func (f TextFormat) AppendDurations(buf *bytes.Buffer, value []time.Duration)

func (TextFormat) AppendFloat added in v1.3.0 

func (f TextFormat) AppendFloat(buf *bytes.Buffer, value float64)

func (TextFormat) AppendFloats added in v1.3.0 

func (f TextFormat) AppendFloats(buf *bytes.Buffer, value []float64)

func (TextFormat) AppendInt added in v1.3.0 

func (f TextFormat) AppendInt(buf *bytes.Buffer, value int)

func (TextFormat) AppendInts added in v1.3.0 

func (f TextFormat) AppendInts(buf *bytes.Buffer, value []int)

func (TextFormat) AppendKey added in v1.3.0 

func (f TextFormat) AppendKey(buf *bytes.Buffer, key string)

func (TextFormat) AppendLevel 

func (f TextFormat) AppendLevel(buf *bytes.Buffer, lvl LEVEL)

func (TextFormat) AppendMsg 

func (f TextFormat) AppendMsg(buf *bytes.Buffer, a ...interface{})

func (TextFormat) AppendMsgf 

func (f TextFormat) AppendMsgf(buf *bytes.Buffer, s string, a ...interface{})

func (TextFormat) AppendString added in v1.3.0 

func (f TextFormat) AppendString(buf *bytes.Buffer, value string)

func (TextFormat) AppendStrings added in v1.3.0 

func (f TextFormat) AppendStrings(buf *bytes.Buffer, value []string)

func (TextFormat) AppendTime added in v1.3.0 

func (f TextFormat) AppendTime(buf *bytes.Buffer, value time.Time)

func (TextFormat) AppendTimes added in v1.3.0 

func (f TextFormat) AppendTimes(buf *bytes.Buffer, value []time.Time)

func (TextFormat) AppendTimestamp 

func (f TextFormat) AppendTimestamp(buf *bytes.Buffer, now string)

func (TextFormat) AppendUint added in v1.3.0 

func (f TextFormat) AppendUint(buf *bytes.Buffer, value uint)

func (TextFormat) AppendUints added in v1.3.0 

func (f TextFormat) AppendUints(buf *bytes.Buffer, value []uint)

func (TextFormat) AppendValue added in v1.2.0 

func (f TextFormat) AppendValue(buf *bytes.Buffer, value interface{})

Source Files

View all Source files

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.
JackTT - Gopher 🇻🇳