logger

README

logger is a fast Go logging package made to be simple but effective.

Overview

Install with:

go get github.com/hamba/logger/v2

Formatters

• JSON
• Logfmt
• Console

Writers

• SyncWriter Write synchronised to a Writer

Note: This project has renamed the default branch from master to main. You will need to update your local environment.

Examples

log := logger.New(os.Stdout, logger.LogfmtFormat(), logger.Info)

// Logger can have scoped context
log = log.With(ctx.Str("env", "prod"))

// All messages can have a context
log.Warn("connection error", ctx.Str("redis", "dsn_1"), ctx.Int("timeout", conn.Timeout()))

Will log the message

lvl=warn msg="connection error" env=prod redis=dsn_1 timeout=0.500

More examples can be found in the godocs.

Documentation

Overview

Package logger implements a logging package.

Example usage:

log := logger.New(os.Stdout, logger.LogfmtFormat(), logger.Info)

// Logger can have scoped context
log = log.With(ctx.Str("env", "prod"))

// All messages can have a context
log.Error("connection error", ctx.Str("redis", conn.Name()), ctx.Int("timeout", conn.Timeout()))

Index

• Constants
• Variables
• type Event
  • func (e *Event) AppendBool(k string, b bool)
  • func (e *Event) AppendBytes(k string, p []byte)
  • func (e *Event) AppendDuration(k string, d time.Duration)
  • func (e *Event) AppendFloat(k string, f float64)
  • func (e *Event) AppendInt(k string, i int64)
  • func (e *Event) AppendInterface(k string, v interface{})
  • func (e *Event) AppendInts(k string, a []int)
  • func (e *Event) AppendString(k, s string)
  • func (e *Event) AppendStrings(k string, s []string)
  • func (e *Event) AppendTime(k string, d time.Time)
  • func (e *Event) AppendUint(k string, i uint64)
• type Field
• type Formatter
  • func ConsoleFormat() Formatter
  • func JSONFormat() Formatter
  • func LogfmtFormat() Formatter
• type Level
  • func LevelFromString(lvl string) (Level, error)
  • func (l Level) String() string
• type Logger
  • func New(w io.Writer, fmtr Formatter, lvl Level) *Logger
  • func (l *Logger) Crit(msg string, ctx ...Field)
  • func (l *Logger) Debug(msg string, ctx ...Field)
  • func (l *Logger) Error(msg string, ctx ...Field)
  • func (l *Logger) Info(msg string, ctx ...Field)
  • func (l *Logger) Trace(msg string, ctx ...Field)
  • func (l *Logger) Warn(msg string, ctx ...Field)
  • func (l *Logger) With(ctx ...Field) *Logger
  • func (l *Logger) WithTimestamp() (cancel func())
  • func (l *Logger) Writer(lvl Level) io.Writer
• type SyncWriter
  • func NewSyncWriter(w io.Writer) *SyncWriter
  • func (w *SyncWriter) Write(p []byte) (n int, err error)

Examples

• New
• SyncWriter

Constants

const (
	// TimestampKey is the key used for timestamps.
	TimestampKey = "ts"
	// LevelKey is the key used for message levels.
	LevelKey = "lvl"
	// MessageKey is the key used for message descriptions.
	MessageKey = "msg"
)

const (
	TimeFormatUnix    = ""
	TimeFormatISO8601 = "2006-01-02T15:04:05-0700"
)

Time formats.

Variables

var TimeFormat = TimeFormatUnix

TimeFormat is the format that times will be added in.

TimeFormat defaults to unix time.

Types

type Event

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

Event is a log event.

func (*Event) AppendBool

func (e *Event) AppendBool(k string, b bool)

AppendBool appends a bool to the event.

func (*Event) AppendBytes

func (e *Event) AppendBytes(k string, p []byte)

AppendBytes appends bytes to the event.

func (*Event) AppendDuration

func (e *Event) AppendDuration(k string, d time.Duration)

AppendDuration appends a duration to the event.

func (*Event) AppendFloat

func (e *Event) AppendFloat(k string, f float64)

AppendFloat appends a float to the event.

func (*Event) AppendInt

func (e *Event) AppendInt(k string, i int64)

AppendInt appends an int to the event.

func (*Event) AppendInterface

func (e *Event) AppendInterface(k string, v interface{})

AppendInterface appends a interface to the event.

func (*Event) AppendInts

func (e *Event) AppendInts(k string, a []int)

AppendInts appends ints to the event.

func (*Event) AppendString

func (e *Event) AppendString(k, s string)

AppendString appends a string to the event.

func (*Event) AppendStrings

func (e *Event) AppendStrings(k string, s []string)

AppendStrings appends strings to the event.

func (*Event) AppendTime

func (e *Event) AppendTime(k string, d time.Time)

AppendTime appends a time to the event.

func (*Event) AppendUint

func (e *Event) AppendUint(k string, i uint64)

AppendUint appends a uint to the event.

type Field

type Field func(*Event)

Field is a context field.

type Formatter

type Formatter interface {
	WriteMessage(buf *bytes.Buffer, ts time.Time, lvl Level, msg string)
	AppendBeginMarker(buf *bytes.Buffer)
	AppendEndMarker(buf *bytes.Buffer)
	AppendLineBreak(buf *bytes.Buffer)
	AppendArrayStart(buf *bytes.Buffer)
	AppendArraySep(buf *bytes.Buffer)
	AppendArrayEnd(buf *bytes.Buffer)
	AppendKey(buf *bytes.Buffer, key string)
	AppendString(buf *bytes.Buffer, s string)
	AppendBool(buf *bytes.Buffer, b bool)
	AppendInt(buf *bytes.Buffer, i int64)
	AppendUint(buf *bytes.Buffer, i uint64)
	AppendFloat(buf *bytes.Buffer, f float64)
	AppendTime(buf *bytes.Buffer, t time.Time)
	AppendDuration(buf *bytes.Buffer, d time.Duration)
	AppendInterface(buf *bytes.Buffer, v interface{})
}

Formatter represents a log message formatter.

func ConsoleFormat

func ConsoleFormat() Formatter

ConsoleFormat formats a log line in a console format.

func JSONFormat

func JSONFormat() Formatter

JSONFormat formats a log line in json format.

func LogfmtFormat

func LogfmtFormat() Formatter

LogfmtFormat formats a log line in logfmt format.

type Level

type Level int

Level represents the predefined log level.

const (
	Disabled Level = iota
	Crit
	Error
	Warn
	Info
	Debug
	Trace
)

List of predefined log Levels.

func LevelFromString

func LevelFromString(lvl string) (Level, error)

LevelFromString converts a string to Level.

func (Level) String

func (l Level) String() string

String returns the string representation of the level.

type Logger

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

Logger is a logger.

func New

func New(w io.Writer, fmtr Formatter, lvl Level) *Logger

New creates a new Logger.

Example

log := logger.New(os.Stdout, logger.LogfmtFormat(), logger.Info).With(ctx.Str("env", "prod"))

log.Info("redis connection", ctx.Str("redis", "some redis name"), ctx.Int("timeout", 10))

func (*Logger) Crit

func (l *Logger) Crit(msg string, ctx ...Field)

Crit logs a critical message.

func (*Logger) Debug

func (l *Logger) Debug(msg string, ctx ...Field)

Debug logs a debug message.

func (*Logger) Error

func (l *Logger) Error(msg string, ctx ...Field)

Error logs an error message.

func (*Logger) Info

func (l *Logger) Info(msg string, ctx ...Field)

Info logs an informational message.

func (*Logger) Trace

func (l *Logger) Trace(msg string, ctx ...Field)

Trace logs a trace message, intended for fine grained debug messages.

func (*Logger) Warn

func (l *Logger) Warn(msg string, ctx ...Field)

Warn logs a warning message.

func (*Logger) With

func (l *Logger) With(ctx ...Field) *Logger

With returns a new Logger with the given context.

func (*Logger) WithTimestamp

func (l *Logger) WithTimestamp() (cancel func())

WithTimestamp adds a timestamp to each log lone. Sub-loggers will inherit the timestamp.

WithTimestamp is not thread safe.

func (*Logger) Writer

func (l *Logger) Writer(lvl Level) io.Writer

Writer returns an io.Writer that writes at the given level. This can be used as a writer with the standard log library.

type SyncWriter

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

SyncWriter implements a writer that is synchronised with a lock.

Example

log := logger.New(logger.NewSyncWriter(os.Stdout), logger.LogfmtFormat(), logger.Info).With(ctx.Str("env", "prod"))

log.Info("redis connection", ctx.Str("redis", "some redis name"), ctx.Int("timeout", 10))

func NewSyncWriter

func NewSyncWriter(w io.Writer) *SyncWriter

NewSyncWriter returns a synchronised writer.

func (*SyncWriter) Write

func (w *SyncWriter) Write(p []byte) (n int, err error)

Write writes to the writer.