logging

README

Logging Package

This package provides a simple logging implementation.

Stability

1.0.0 will be contain a stable API.

Documentation

Index

• Variables
• func Debug(msg string, args ...interface{})
• func Error(msg string, args ...interface{})
• func Fatal(msg string, args ...interface{})
• func Info(msg string, args ...interface{})
• func NewContext(ctx context.Context, log *Log) context.Context
• func Panic(msg string, args ...interface{})
• func Warning(msg string, args ...interface{})
• type Entry
• type Field
• type Level
  • func (l Level) Equals(v string) bool
  • func (l Level) Is(lvl Level) bool
  • func (l Level) MarshalSetting() string
  • func (l Level) Prefix() string
  • func (l Level) Short() string
  • func (l Level) String() string
  • func (l *Level) UnmarshalSetting(v string) error
• type Log
  • func FromContext(ctx context.Context) *Log
  • func New(opts ...Option) *Log
  • func (l *Log) Critical(msg string, args ...interface{})
  • func (l *Log) Debug(msg string, args ...interface{})
  • func (l *Log) Error(msg string, args ...interface{})
  • func (l *Log) Info(msg string, args ...interface{})
  • func (l *Log) Trace(msg string, args ...interface{})
  • func (l *Log) Warning(msg string, args ...interface{})
  • func (l *Log) WithFields(fields ...Field) *Log
  • func (l *Log) Write(lvl Level, msg string, args ...interface{})
• type Option
  • func WithFields(fields ...Field) Option
  • func WithWriter(w Writer) Option
  • func (o Option) Apply(l *Log)
• type Writer
• type WriterFunc
  • func (w WriterFunc) Write(e Entry)

Variables

var (
	// DefaultLog is the *Log used in static functions and is returned from contexts when no *Log is present
	DefaultLog = &Log{writer: Discard}
)

var Discard = WriterFunc(func(Entry) {})

Discard will drop the log entries into the abyss (or do nothing)

Functions

func Debug

func Debug(msg string, args ...interface{})

Debug log message

func Error

func Error(msg string, args ...interface{})

Error log message

func Fatal

func Fatal(msg string, args ...interface{})

Fatal log message, and exit -1

func Info

func Info(msg string, args ...interface{})

Info log message

func NewContext

func NewContext(ctx context.Context, log *Log) context.Context

NewContext creates a child context of the supplied context embedding the *Log. This *Log can be retrieved with the FromContext

func Panic

func Panic(msg string, args ...interface{})

Panic log message - calls panic

func Warning

func Warning(msg string, args ...interface{})

Warning log message

Types

type Entry

type Entry struct {
	Level     Level
	Timestamp time.Time
	Message   string
	Arguments []interface{}
	Fields    []Field
}

Entry represents a single log

type Field

type Field struct {
	Name  string
	Value interface{}
}

Field for structured logging

type Level

type Level uint8

Level for logging Levels are defaulted to that of syslog severity level https://en.wikipedia.org/wiki/Syslog

Interpretation of the Levels is up to the appliation that is using them, the comments provided are only recommendations

const (
	// LevelEmergency - A panic condition.
	LevelEmergency Level = iota

	// LevelAlert - A condition that should be corrected immediately, such as a corrupted system database.
	LevelAlert

	// LevelCritical - Hard application/device/hardware failures
	LevelCritical

	// LevelError - non-recoverable application errors
	LevelError

	// LevelWarning - recoverable application errors
	LevelWarning

	// LevelNotice - Conditions that are not error conditions, but may require special handling
	LevelNotice

	// LevelInformational - Messages that contain information about the application operation
	LevelInformational

	// LevelDebug - Messages that contain information normally of use only when debugging a program
	LevelDebug

	// LevelTrace - Messages that are likely only using while developing applications
	//
	// This is not part of the syslog spec, and might not be supported by all logging.Writer implementations
	LevelTrace

	// LevelNone - Not inteded to have output
	LevelNone Level = 255
)

func (Level) Equals

func (l Level) Equals(v string) bool

Equals returns if the current value matches the input

func (Level) Is

func (l Level) Is(lvl Level) bool

Is will return if the provided Level is verbose enough from the current level. This is suitable for checking before outputing logs

i.e. entry.Level.Is(LevelDebug) => write it when Debug-Emergency Level

func (Level) MarshalSetting

func (l Level) MarshalSetting() string

MarshalSetting provides the custom string output for the log level in config

func (Level) Prefix

func (l Level) Prefix() string

Prefix returns the syslog/journald prefix format of <#>

func (Level) Short

func (l Level) Short() string

Short returns the short representation of the level

func (Level) String

func (l Level) String() string

func (*Level) UnmarshalSetting

func (l *Level) UnmarshalSetting(v string) error

UnmarshalSetting provides the custom parsing of log levels in config

type Log

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

Log for ... writing logs

func FromContext

func FromContext(ctx context.Context) *Log

FromContext will return the logger for the specified context or the default one

func New

func New(opts ...Option) *Log

New creates a new Log instance with the specified options

func (*Log) Critical

func (l *Log) Critical(msg string, args ...interface{})

Critical will write a Critical log entry

func (*Log) Debug

func (l *Log) Debug(msg string, args ...interface{})

Debug will write a Debug log entry

func (*Log) Error

func (l *Log) Error(msg string, args ...interface{})

Error will write an Error log entry

func (*Log) Info

func (l *Log) Info(msg string, args ...interface{})

Info will write an Informational log entry

func (*Log) Trace

func (l *Log) Trace(msg string, args ...interface{})

Trace will write a Trace log entry

func (*Log) Warning

func (l *Log) Warning(msg string, args ...interface{})

Warning will write a Warning log entry

func (*Log) WithFields

func (l *Log) WithFields(fields ...Field) *Log

WithFields will create a child logger sharing the same output as the parent with the additional fields specified

func (*Log) Write

func (l *Log) Write(lvl Level, msg string, args ...interface{})

type Option

type Option func(*Log)

Option for logging

func WithFields

func WithFields(fields ...Field) Option

WithFields options will append the specified fields to the Log

func WithWriter

func WithWriter(w Writer) Option

WithWriter option will set the underlying write for the logs

func (Option) Apply

func (o Option) Apply(l *Log)

Apply aa Option to the specified Log

type Writer

type Writer interface {
	Write(e Entry)
}

Writer interface for putting log Entry somewhere, someway

type WriterFunc

type WriterFunc func(e Entry)

WriterFunc implements the logging.Writer interface to cast functions to the Writer

func (WriterFunc) Write

func (w WriterFunc) Write(e Entry)