logger

Documentation

Overview

Package logger provides tiny structured logging abstraction or facade for various logging libraries, allowing the end user to plug in the desired logging library in main.go.

Index

• type Adapter
• type Entry
  • func (e Entry) With(field Field) Entry
  • func (e Entry) WithFields(fields Fields) Entry
• type Field
• type Fields
• type Global
  • func (g *Global) Debug(ctx context.Context, msg string)
  • func (g *Global) DebugFields(ctx context.Context, msg string, fields Fields)
  • func (g *Global) Error(ctx context.Context, msg string)
  • func (g *Global) ErrorCause(ctx context.Context, msg string, cause error)
  • func (g *Global) ErrorCauseFields(ctx context.Context, msg string, cause error, fields Fields)
  • func (g *Global) ErrorFields(ctx context.Context, msg string, fields Fields)
  • func (g *Global) Info(ctx context.Context, msg string)
  • func (g *Global) InfoFields(ctx context.Context, msg string, fields Fields)
  • func (g *Global) SetAdapter(adapter Adapter)
  • func (g *Global) Warn(ctx context.Context, msg string)
  • func (g *Global) WarnFields(ctx context.Context, msg string, fields Fields)
  • func (g *Global) With(key string, value interface{}) *Global
  • func (g *Global) WithError(err error) *Global
  • func (g *Global) WithFields(fields Fields) *Global
  • func (g *Global) WithSkippedCallerFrame() *Global
• type Level
  • func (l Level) MoreSevereThan(other Level) bool
  • func (l Level) String() string
• type Logger
  • func WithAdapter(adapter Adapter) Logger
  • func (l Logger) Debug(ctx context.Context, msg string)
  • func (l Logger) DebugFields(ctx context.Context, msg string, fields Fields)
  • func (l Logger) Error(ctx context.Context, msg string)
  • func (l Logger) ErrorCause(ctx context.Context, msg string, cause error)
  • func (l Logger) ErrorCauseFields(ctx context.Context, msg string, cause error, fields Fields)
  • func (l Logger) ErrorFields(ctx context.Context, msg string, fields Fields)
  • func (l Logger) Info(ctx context.Context, msg string)
  • func (l Logger) InfoFields(ctx context.Context, msg string, fields Fields)
  • func (l Logger) Warn(ctx context.Context, msg string)
  • func (l Logger) WarnFields(ctx context.Context, msg string, fields Fields)
  • func (l Logger) With(key string, value interface{}) Logger
  • func (l Logger) WithError(err error) Logger
  • func (l Logger) WithFields(fields Fields) Logger
  • func (l Logger) WithSkippedCallerFrame() Logger

Types

type Adapter

type Adapter interface {
	Log(context.Context, Entry)
}

Adapter is an interface to be implemented by logger adapters.

type Entry

type Entry struct {
	Level   Level
	Message string

	// Fields contains all accumulated fields, in the order they were appended.
	//
	// Please do not modify the slice directly as other go-routines may still read it.  To append a new field
	// please use With method. It will create a new entry with copy of all fields, plus the new one. To remove a field,
	// please create a new slice and copy remaining fields.
	// To update fields you can rewrite entire slice.
	//
	// Fields can be nil.
	Fields []Field

	Error error // Error can be nil
	// SkippedCallerFrames can be used by logger.Adapter to extract caller information (file and line number)
	SkippedCallerFrames int
}

Entry is a logging entry created by logger and passed to adapter.

func (Entry) With

func (e Entry) With(field Field) Entry

With creates a new entry with additional field.

func (Entry) WithFields

func (e Entry) WithFields(fields Fields) Entry

WithFields creates a new entry with additional fields. Fields will be appended, not replaced.

type Field

type Field struct {
	Key   string
	Value interface{}
}

Field contains key-value pair.

type Fields

type Fields map[string]interface{}

type Global

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

Global is a logger shared globally. You can use it to define global logger for your package:

package yourpackage
import "github.com/elgopher/yala/logger"

var log logger.Global // define global logger, no need to initialize (by default nothing is logged)

func SetLoggerAdapter(adapter logger.Adapter) {
	log.SetAdapter(adapter)
}

It is safe to use it concurrently.

Please do not copy logger.Global instance. If you want to create a child logger, please use With and WithError methods. These methods will create *logger.Global using shared adapter.

func (*Global) Debug

func (g *Global) Debug(ctx context.Context, msg string)

Debug logs a message at DebugLevel.

func (*Global) DebugFields

func (g *Global) DebugFields(ctx context.Context, msg string, fields Fields)

DebugFields logs a message at DebugLevel with fields.

func (*Global) Error

func (g *Global) Error(ctx context.Context, msg string)

Error logs a message at ErrorLevel.

func (*Global) ErrorCause

func (g *Global) ErrorCause(ctx context.Context, msg string, cause error)

ErrorCause logs a message at ErrorLevel with cause.

func (*Global) ErrorCauseFields

func (g *Global) ErrorCauseFields(ctx context.Context, msg string, cause error, fields Fields)

ErrorCauseFields logs a message at ErrorLevel with cause and fields.

func (*Global) ErrorFields

func (g *Global) ErrorFields(ctx context.Context, msg string, fields Fields)

ErrorFields logs a message at ErrorLevel with fields.

func (*Global) Info

func (g *Global) Info(ctx context.Context, msg string)

Info logs a message at InfoLevel.

func (*Global) InfoFields

func (g *Global) InfoFields(ctx context.Context, msg string, fields Fields)

InfoFields logs a message at InfoLevel with fields.

func (*Global) SetAdapter

func (g *Global) SetAdapter(adapter Adapter)

SetAdapter updates adapter implementation. By default, nothing is logged.

It can be run anytime. Please note though that this method is meant to be used by end user, configuring logging from the central place (such as main.go or any other package setting up the entire application).

If this method is called on an instance created using With* methods, then all parent and child loggers are updated too.

func (*Global) Warn

func (g *Global) Warn(ctx context.Context, msg string)

Warn logs a message at WarnLevel.

func (*Global) WarnFields

func (g *Global) WarnFields(ctx context.Context, msg string, fields Fields)

WarnFields logs a message at WarnLevel with fields.

func (*Global) With

func (g *Global) With(key string, value interface{}) *Global

With creates a new child logger with additional field.

func (*Global) WithError

func (g *Global) WithError(err error) *Global

WithError creates a new child logger with error.

func (*Global) WithFields

func (g *Global) WithFields(fields Fields) *Global

WithFields creates a new logger with additional fields.

func (*Global) WithSkippedCallerFrame

func (g *Global) WithSkippedCallerFrame() *Global

WithSkippedCallerFrame creates a new child logger with one more skipped caller frame. This function is handy when you want to write your own logging helpers.

type Level

type Level int8

Level is a severity level of message. Use Level.MoreSevereThan to compare two levels.

const (
	// DebugLevel level is usually enabled only when debugging (disabled in production). Very verbose logging.
	DebugLevel Level = iota - 1
	// InfoLevel is used for informational messages, for confirmation that the program is working as expected.
	InfoLevel
	// WarnLevel is used for non-critical entries that deserve eyes.
	WarnLevel
	// ErrorLevel is used for errors that should definitely be noted. If an application is running smoothly,
	// it shouldn't generate any error-level logs.
	ErrorLevel
)

func (Level) MoreSevereThan

func (l Level) MoreSevereThan(other Level) bool

MoreSevereThan returns true if level is more severe than the argument.

func (Level) String

func (l Level) String() string

String converts the Level to a string. For example InfoLevel becomes "INFO".

type Logger

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

Logger is an immutable logger to log messages or create new loggers with fields or error.

You can't update the adapter once created.

It is safe to use it concurrently.

func WithAdapter

func WithAdapter(adapter Adapter) Logger

WithAdapter creates a new Logger.

func (Logger) Debug

func (l Logger) Debug(ctx context.Context, msg string)

Debug logs a message at DebugLevel.

func (Logger) DebugFields

func (l Logger) DebugFields(ctx context.Context, msg string, fields Fields)

DebugFields logs a message at DebugLevel with fields.

func (Logger) Error

func (l Logger) Error(ctx context.Context, msg string)

Error logs a message at ErrorLevel.

func (Logger) ErrorCause

func (l Logger) ErrorCause(ctx context.Context, msg string, cause error)

ErrorCause logs a message at ErrorLevel with cause.

func (Logger) ErrorCauseFields

func (l Logger) ErrorCauseFields(ctx context.Context, msg string, cause error, fields Fields)

ErrorCauseFields logs a message at ErrorLevel with cause and fields.

func (Logger) ErrorFields

func (l Logger) ErrorFields(ctx context.Context, msg string, fields Fields)

ErrorFields logs a message at ErrorLevel with fields.

func (Logger) Info

func (l Logger) Info(ctx context.Context, msg string)

Info logs a message at InfoLevel.

func (Logger) InfoFields

func (l Logger) InfoFields(ctx context.Context, msg string, fields Fields)

InfoFields logs a message at InfoLevel with fields.

func (Logger) Warn

func (l Logger) Warn(ctx context.Context, msg string)

Warn logs a message at WarnLevel.

func (Logger) WarnFields

func (l Logger) WarnFields(ctx context.Context, msg string, fields Fields)

WarnFields logs a message at WarnLevel with fields.

func (Logger) With

func (l Logger) With(key string, value interface{}) Logger

With creates a new logger with additional field.

func (Logger) WithError

func (l Logger) WithError(err error) Logger

WithError creates a new logger with error.

func (Logger) WithFields

func (l Logger) WithFields(fields Fields) Logger

WithFields creates a new logger with additional fields.

func (Logger) WithSkippedCallerFrame

func (l Logger) WithSkippedCallerFrame() Logger

WithSkippedCallerFrame creates a new logger with one more skipped caller frame. This function is handy when you want to write your own logging helpers.