logur: logur.dev/logur Index | Files | Directories

package logur

import "logur.dev/logur"

Package logur is an opinionated collection of logging best practices.

Check the readme for detailed documentation: https://github.com/logur/logur/blob/master/README.md

Also, check the example package for detailed examples: https://godoc.org/logur.dev/logur/examples

Index

Package Files

doc.go levels.go logger.go logger_context.go logger_fields.go logger_print.go logger_testing.go standard_logger.go utils.go writer.go

func LogEventsEqual Uses

func LogEventsEqual(expected LogEvent, actual LogEvent) error

LogEventsEqual asserts that two LogEvents are identical and returns an error with detailed information if not.

Deprecated: use LogEvents.AssertEquals.

func NewErrorStandardLogger Uses

func NewErrorStandardLogger(logger Logger, prefix string, flag int) *log.Logger

NewErrorStandardLogger returns a new standard library logger for error level logging (eg. for HTTP servers).

func NewLevelWriter Uses

func NewLevelWriter(logger Logger, level Level) *io.PipeWriter

NewLevelWriter creates a new writer from a Logger for a specific level of log events.

func NewStandardLogger Uses

func NewStandardLogger(logger Logger, level Level, prefix string, flag int) *log.Logger

NewStandardLogger returns a new standard library logger.

func NewWriter Uses

func NewWriter(logger Logger) *io.PipeWriter

NewWriter creates a new writer from a Logger with a default Info level.

type ContextExtractor Uses

type ContextExtractor func(ctx context.Context) map[string]interface{}

ContextExtractor extracts a map of details from a context.

func ContextExtractors Uses

func ContextExtractors(extractors ...ContextExtractor) ContextExtractor

ContextExtractors combines a list of ContextExtractor. The returned extractor aggregates the result of the underlying extractors.

type Fields Uses

type Fields map[string]interface{}

Fields is used to define structured fields which are appended to log events. It can be used as a shorthand for map[string]interface{}.

type KVLogContextFunc Uses

type KVLogContextFunc func(ctx context.Context, msg string, keyvals ...interface{})

KVLogContextFunc records a log event.

func KVLevelContextFunc Uses

func KVLevelContextFunc(l KVLogger, level Level) KVLogContextFunc

KVLevelContextFunc returns a KVLogContextFunc for a level. If the level is invalid it falls back to Info level.

type KVLogFunc Uses

type KVLogFunc func(msg string, keyvals ...interface{})

KVLogFunc records a log event.

func KVLevelFunc Uses

func KVLevelFunc(logger KVLogger, level Level) KVLogFunc

KVLevelFunc returns a KVLogFunc for a level. If the level is invalid it falls back to Info level.

type KVLogger Uses

type KVLogger interface {
    // Trace logs a Trace event.
    //
    // Even more fine-grained information than Debug events.
    // Loggers not supporting this level should fall back to Debug.
    Trace(msg string, keyvals ...interface{})

    // Debug logs a Debug event.
    //
    // A verbose series of information events.
    // They are useful when debugging the system.
    Debug(msg string, keyvals ...interface{})

    // Info logs an Info event.
    //
    // General information about what's happening inside the system.
    Info(msg string, keyvals ...interface{})

    // Warn logs a Warn(ing) event.
    //
    // Non-critical events that should be looked at.
    Warn(msg string, keyvals ...interface{})

    // Error logs an Error event.
    //
    // Critical events that require immediate attention.
    // Loggers commonly provide Fatal and Panic levels above Error level,
    // but exiting and panicing is out of scope for a logging library.
    Error(msg string, keyvals ...interface{})
}

KVLogger is a unified interface for various logging use cases and practices, including:

- leveled logging
- structured logging

Compared to Logger, KVLogger accepts key-value pairs in the form of variadic interface arguments.

type KVLoggerContext Uses

type KVLoggerContext interface {
    // TraceContext logs a Trace event.
    //
    // Even more fine-grained information than Debug events.
    // Loggers not supporting this level should fall back to Debug.
    TraceContext(ctx context.Context, msg string, keyvals ...interface{})

    // DebugContext logs a Debug event.
    //
    // A verbose series of information events.
    // They are useful when debugging the system.
    DebugContext(ctx context.Context, msg string, keyvals ...interface{})

    // InfoContext logs an Info event.
    //
    // General information about what's happening inside the system.
    InfoContext(ctx context.Context, msg string, keyvals ...interface{})

    // WarnContext logs a Warn(ing) event.
    //
    // Non-critical events that should be looked at.
    WarnContext(ctx context.Context, msg string, keyvals ...interface{})

    // ErrorContext logs an Error event.
    //
    // Critical events that require immediate attention.
    // Loggers commonly provide Fatal and Panic levels above Error level,
    // but exiting and panicing is out of scope for a logging library.
    ErrorContext(ctx context.Context, msg string, keyvals ...interface{})
}

KVLoggerContext is an optional interface that MAY be implemented by a KVLogger. It is similar to KVLogger, but it receives a context as the first parameter. An implementation MAY extract information from the context and annotate the log context with it.

KVLoggerContext MAY honor the deadline carried by the context, but that's not a hard requirement.

type KVLoggerFacade Uses

type KVLoggerFacade interface {
    KVLogger
    KVLoggerContext
}

KVLoggerFacade is a combination of KVLogger and KVLoggerContext. It's sole purpose is to make the API of the package concise by exposing a common interface type for returned loggers. It's not supposed to be used by consumers of this package.

It goes directly against the "Use interfaces, return structs" idiom of Go, but at the current phase of the package the smaller API surface makes more sense.

In the future it might get replaced with concrete types.

func LoggerToKV Uses

func LoggerToKV(logger Logger) KVLoggerFacade

LoggerToKV converts a Logger to a KVLogger.

type Level Uses

type Level uint32

Level represents the same levels as defined in Logger.

const (
    // Even more fine-grained information than Debug events.
    // Loggers not supporting this level should fall back to Debug.
    Trace Level = iota

    // A verbose series of information events.
    // They are useful when debugging the system.
    Debug

    // General information about what's happening inside the system.
    Info

    // Non-critical events that should be looked at.
    Warn

    // Critical events that require immediate attention.
    Error
)

Levels as defined in Logger.

func Levels Uses

func Levels() []Level

Levels returns a list of available Level values.

func ParseLevel Uses

func ParseLevel(level string) (Level, bool)

ParseLevel takes a string level and returns the defined log level constant. If the level is not defined, it returns false as the second parameter.

func (Level) String Uses

func (l Level) String() string

String converts a Level to string.

func (*Level) UnmarshalText Uses

func (l *Level) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type LevelEnabler Uses

type LevelEnabler interface {
    // LevelEnabled checks if a level is enabled in a logger.
    LevelEnabled(level Level) bool
}

LevelEnabler checks if a level is enabled in a logger. If the logger cannot reliably decide the correct level this method MUST return true.

type LogContextFunc Uses

type LogContextFunc func(ctx context.Context, msg string, fields ...map[string]interface{})

LogContextFunc records a log event.

func LevelContextFunc Uses

func LevelContextFunc(l Logger, level Level) LogContextFunc

LevelContextFunc returns a LogContextFunc for a level. If the level is invalid it falls back to Info level.

type LogEvent Uses

type LogEvent struct {
    Line   string
    Level  Level
    Fields map[string]interface{}
}

LogEvent represents a single log event recorded by a test logger.

func (LogEvent) AssertEquals Uses

func (e LogEvent) AssertEquals(other LogEvent) error

AssertEquals checks if two LogEvent instances are equal and returns an error if not.

func (LogEvent) Equals Uses

func (e LogEvent) Equals(other LogEvent) bool

Equals checks if two LogEvent instances are equal.

type LogFunc Uses

type LogFunc func(msg string, fields ...map[string]interface{})

LogFunc records a log event.

func LevelFunc Uses

func LevelFunc(logger Logger, level Level) LogFunc

LevelFunc returns a LogFunc for a level. If the level is invalid it falls back to Info level.

type Logger Uses

type Logger interface {
    // Trace logs a Trace event.
    //
    // Even more fine-grained information than Debug events.
    // Loggers not supporting this level should fall back to Debug.
    Trace(msg string, fields ...map[string]interface{})

    // Debug logs a Debug event.
    //
    // A verbose series of information events.
    // They are useful when debugging the system.
    Debug(msg string, fields ...map[string]interface{})

    // Info logs an Info event.
    //
    // General information about what's happening inside the system.
    Info(msg string, fields ...map[string]interface{})

    // Warn logs a Warn(ing) event.
    //
    // Non-critical events that should be looked at.
    Warn(msg string, fields ...map[string]interface{})

    // Error logs an Error event.
    //
    // Critical events that require immediate attention.
    // Loggers commonly provide Fatal and Panic levels above Error level,
    // but exiting and panicing is out of scope for a logging library.
    Error(msg string, fields ...map[string]interface{})
}

Logger is a unified interface for various logging use cases and practices, including:

- leveled logging
- structured logging

func NewNoopLogger Uses

func NewNoopLogger() Logger

NewNoopLogger creates a no-op logger that discards all received log events. Useful in examples and as a fallback logger.

Deprecated: use NoopLogger.

type LoggerContext Uses

type LoggerContext interface {
    // TraceContext logs a Trace event.
    //
    // Even more fine-grained information than Debug events.
    // Loggers not supporting this level should fall back to Debug.
    TraceContext(ctx context.Context, msg string, fields ...map[string]interface{})

    // DebugContext logs a Debug event.
    //
    // A verbose series of information events.
    // They are useful when debugging the system.
    DebugContext(ctx context.Context, msg string, fields ...map[string]interface{})

    // InfoContext logs an Info event.
    //
    // General information about what's happening inside the system.
    InfoContext(ctx context.Context, msg string, fields ...map[string]interface{})

    // WarnContext logs a Warn(ing) event.
    //
    // Non-critical events that should be looked at.
    WarnContext(ctx context.Context, msg string, fields ...map[string]interface{})

    // ErrorContext logs an Error event.
    //
    // Critical events that require immediate attention.
    // Loggers commonly provide Fatal and Panic levels above Error level,
    // but exiting and panicing is out of scope for a logging library.
    ErrorContext(ctx context.Context, msg string, fields ...map[string]interface{})
}

LoggerContext is an optional interface that MAY be implemented by a Logger. It is similar to Logger, but it receives a context as the first parameter. An implementation MAY extract information from the context and annotate the log context with it.

LoggerContext MAY honor the deadline carried by the context, but that's not a hard requirement.

type LoggerFacade Uses

type LoggerFacade interface {
    Logger
    LoggerContext
}

LoggerFacade is a combination of Logger and LoggerContext. It's sole purpose is to make the API of the package concise by exposing a common interface type for returned loggers. It's not supposed to be used by consumers of this package.

It goes directly against the "Use interfaces, return structs" idiom of Go, but at the current phase of the package the smaller API surface makes more sense.

In the future it might get replaced with concrete types.

func WithContextExtractor Uses

func WithContextExtractor(logger Logger, extractor ContextExtractor) LoggerFacade

WithContextExtractor returns a logger that extracts details from the provided context (if any) and annotates the log event with them.

func WithField Uses

func WithField(logger Logger, key string, value interface{}) LoggerFacade

WithField is a shortcut for WithFields(logger, map[string]interface{}{key: value}).

func WithFields Uses

func WithFields(logger Logger, fields map[string]interface{}) LoggerFacade

WithFields returns a new logger instance that attaches the given fields to every subsequent log call.

type MessageLogger Uses

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

MessageLogger simplifies the Logger interface by removing the second context parameter. Useful when there is no need for contextual logging.

func NewMessageLogger Uses

func NewMessageLogger(logger Logger) *MessageLogger

NewMessageLogger returns a new MessageLogger instance.

func (*MessageLogger) Debug Uses

func (l *MessageLogger) Debug(msg string)

Debug logs a Debug level event.

func (*MessageLogger) Error Uses

func (l *MessageLogger) Error(msg string)

Error logs a Error level event.

func (*MessageLogger) Info Uses

func (l *MessageLogger) Info(msg string)

Info logs a Info level event.

func (*MessageLogger) Trace Uses

func (l *MessageLogger) Trace(msg string)

Trace logs a Trace level event.

func (*MessageLogger) Warn Uses

func (l *MessageLogger) Warn(msg string)

Warn logs a Warn level event.

type NoopKVLogger Uses

type NoopKVLogger struct{}

NoopKVLogger is a no-op logger that discards all received log events.

It implements both KVLogger and KVLoggerContext interfaces.

func (NoopKVLogger) Debug Uses

func (NoopKVLogger) Debug(_ string, _ ...interface{})

func (NoopKVLogger) DebugContext Uses

func (NoopKVLogger) DebugContext(_ context.Context, _ string, _ ...interface{})

func (NoopKVLogger) Error Uses

func (NoopKVLogger) Error(_ string, _ ...interface{})

func (NoopKVLogger) ErrorContext Uses

func (NoopKVLogger) ErrorContext(_ context.Context, _ string, _ ...interface{})

func (NoopKVLogger) Info Uses

func (NoopKVLogger) Info(_ string, _ ...interface{})

func (NoopKVLogger) InfoContext Uses

func (NoopKVLogger) InfoContext(_ context.Context, _ string, _ ...interface{})

func (NoopKVLogger) Trace Uses

func (NoopKVLogger) Trace(_ string, _ ...interface{})

func (NoopKVLogger) TraceContext Uses

func (NoopKVLogger) TraceContext(_ context.Context, _ string, _ ...interface{})

func (NoopKVLogger) Warn Uses

func (NoopKVLogger) Warn(_ string, _ ...interface{})

func (NoopKVLogger) WarnContext Uses

func (NoopKVLogger) WarnContext(_ context.Context, _ string, _ ...interface{})

type NoopLogger Uses

type NoopLogger struct{}

NoopLogger is a no-op logger that discards all received log events.

It implements both Logger and LoggerContext interfaces.

func (NoopLogger) Debug Uses

func (NoopLogger) Debug(_ string, _ ...map[string]interface{})

func (NoopLogger) DebugContext Uses

func (NoopLogger) DebugContext(_ context.Context, _ string, _ ...map[string]interface{})

func (NoopLogger) Error Uses

func (NoopLogger) Error(_ string, _ ...map[string]interface{})

func (NoopLogger) ErrorContext Uses

func (NoopLogger) ErrorContext(_ context.Context, _ string, _ ...map[string]interface{})

func (NoopLogger) Info Uses

func (NoopLogger) Info(_ string, _ ...map[string]interface{})

func (NoopLogger) InfoContext Uses

func (NoopLogger) InfoContext(_ context.Context, _ string, _ ...map[string]interface{})

func (NoopLogger) Trace Uses

func (NoopLogger) Trace(_ string, _ ...map[string]interface{})

func (NoopLogger) TraceContext Uses

func (NoopLogger) TraceContext(_ context.Context, _ string, _ ...map[string]interface{})

func (NoopLogger) Warn Uses

func (NoopLogger) Warn(_ string, _ ...map[string]interface{})

func (NoopLogger) WarnContext Uses

func (NoopLogger) WarnContext(_ context.Context, _ string, _ ...map[string]interface{})

type PrintLogger Uses

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

PrintLogger logs messages with fmt.Print* function semantics.

func NewErrorPrintLogger Uses

func NewErrorPrintLogger(logger Logger) *PrintLogger

NewErrorPrintLogger returns a new PrintLogger that logs everything on error level.

func NewPrintLogger Uses

func NewPrintLogger(logger LogFunc) *PrintLogger

NewPrintLogger returns a new PrintLogger.

func (*PrintLogger) Print Uses

func (l *PrintLogger) Print(v ...interface{})

Print logs a line with fmt.Print semantics.

func (*PrintLogger) Printf Uses

func (l *PrintLogger) Printf(format string, args ...interface{})

Printf logs a line with fmt.Printf semantics.

func (*PrintLogger) Println Uses

func (l *PrintLogger) Println(v ...interface{})

Println logs a line with fmt.Println semantics.

type TestLogger Uses

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

TestLogger is a Logger recording every log event.

Useful when you want to test behavior with an Logger, but not with LoggerContext. In every other cases TestLoggerFacade should be the default choice of test logger.

The TestLogger is safe for concurrent use.

func NewTestLogger Uses

func NewTestLogger() *TestLogger

NewTestLogger returns a new TestLogger.

Deprecated: use TestLogger.

func (*TestLogger) Count Uses

func (l *TestLogger) Count() int

Count returns the number of events recorded in the logger.

func (*TestLogger) Debug Uses

func (l *TestLogger) Debug(msg string, fields ...map[string]interface{})

Debug records a Debug level event.

func (*TestLogger) Error Uses

func (l *TestLogger) Error(msg string, fields ...map[string]interface{})

Error records an Error level event.

func (*TestLogger) Events Uses

func (l *TestLogger) Events() []LogEvent

Events returns all recorded events in the logger.

func (*TestLogger) Info Uses

func (l *TestLogger) Info(msg string, fields ...map[string]interface{})

Info records an Info level event.

func (*TestLogger) LastEvent Uses

func (l *TestLogger) LastEvent() *LogEvent

LastEvent returns the last recorded event in the logger (if any).

func (*TestLogger) Trace Uses

func (l *TestLogger) Trace(msg string, fields ...map[string]interface{})

Trace records a Trace level event.

func (*TestLogger) Warn Uses

func (l *TestLogger) Warn(msg string, fields ...map[string]interface{})

Warn records a Warn level event.

type TestLoggerContext Uses

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

TestLoggerContext is a LoggerContext recording every log event.

Useful when you want to test behavior with an LoggerContext, but not with Logger. In every other cases TestLoggerFacade should be the default choice of test logger.

The TestLoggerContext is safe for concurrent use.

func (*TestLoggerContext) Count Uses

func (l *TestLoggerContext) Count() int

Count returns the number of events recorded in the logger.

func (*TestLoggerContext) DebugContext Uses

func (l *TestLoggerContext) DebugContext(ctx context.Context, msg string, fields ...map[string]interface{})

DebugContext records a Debug level event.

func (*TestLoggerContext) ErrorContext Uses

func (l *TestLoggerContext) ErrorContext(ctx context.Context, msg string, fields ...map[string]interface{})

ErrorContext records an Error level event.

func (*TestLoggerContext) Events Uses

func (l *TestLoggerContext) Events() []LogEvent

Events returns all recorded events in the logger.

func (*TestLoggerContext) InfoContext Uses

func (l *TestLoggerContext) InfoContext(ctx context.Context, msg string, fields ...map[string]interface{})

InfoContext records an Info level event.

func (*TestLoggerContext) LastEvent Uses

func (l *TestLoggerContext) LastEvent() *LogEvent

LastEvent returns the last recorded event in the logger (if any).

func (*TestLoggerContext) TraceContext Uses

func (l *TestLoggerContext) TraceContext(ctx context.Context, msg string, fields ...map[string]interface{})

TraceContext records a Trace level event.

func (*TestLoggerContext) WarnContext Uses

func (l *TestLoggerContext) WarnContext(ctx context.Context, msg string, fields ...map[string]interface{})

WarnContext records a Warn level event.

type TestLoggerFacade Uses

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

TestLoggerFacade is a LoggerFacade recording every log event.

The TestLoggerFacade is safe for concurrent use.

func (*TestLoggerFacade) Count Uses

func (l *TestLoggerFacade) Count() int

Count returns the number of events recorded in the logger.

func (*TestLoggerFacade) Debug Uses

func (l *TestLoggerFacade) Debug(msg string, fields ...map[string]interface{})

Debug records a Debug level event.

func (*TestLoggerFacade) DebugContext Uses

func (l *TestLoggerFacade) DebugContext(ctx context.Context, msg string, fields ...map[string]interface{})

DebugContext records a Debug level event.

func (*TestLoggerFacade) Error Uses

func (l *TestLoggerFacade) Error(msg string, fields ...map[string]interface{})

Error records an Error level event.

func (*TestLoggerFacade) ErrorContext Uses

func (l *TestLoggerFacade) ErrorContext(ctx context.Context, msg string, fields ...map[string]interface{})

ErrorContext records an Error level event.

func (*TestLoggerFacade) Events Uses

func (l *TestLoggerFacade) Events() []LogEvent

Events returns all recorded events in the logger.

func (*TestLoggerFacade) Info Uses

func (l *TestLoggerFacade) Info(msg string, fields ...map[string]interface{})

Info records an Info level event.

func (*TestLoggerFacade) InfoContext Uses

func (l *TestLoggerFacade) InfoContext(ctx context.Context, msg string, fields ...map[string]interface{})

InfoContext records an Info level event.

func (*TestLoggerFacade) LastEvent Uses

func (l *TestLoggerFacade) LastEvent() *LogEvent

LastEvent returns the last recorded event in the logger (if any).

func (*TestLoggerFacade) Trace Uses

func (l *TestLoggerFacade) Trace(msg string, fields ...map[string]interface{})

Trace records a Trace level event.

func (*TestLoggerFacade) TraceContext Uses

func (l *TestLoggerFacade) TraceContext(ctx context.Context, msg string, fields ...map[string]interface{})

TraceContext records a Trace level event.

func (*TestLoggerFacade) Warn Uses

func (l *TestLoggerFacade) Warn(msg string, fields ...map[string]interface{})

Warn records a Warn level event.

func (*TestLoggerFacade) WarnContext Uses

func (l *TestLoggerFacade) WarnContext(ctx context.Context, msg string, fields ...map[string]interface{})

WarnContext records a Warn level event.

Directories

PathSynopsis
conformance
examples
integration/grpcPackage grpc provides a V2 gRPC logger.
integration/kit
internal/keyvals
logtesting

Package logur imports 9 packages (graph) and is imported by 37 packages. Updated 2020-10-05. Refresh now. Tools for package owners.