slog

README

slog

slog implements a simple structured logging API inspired by apex/log, Logrus and go-playground/log.

Documentation

Overview

Example (Errors)

Errors are passed to WithError(), populating the "error" field.

package main

import (
	"errors"

	"github.com/cv/slog"
)

func main() {
	l := slog.New()
	err := errors.New("boom")
	l.WithError(err).Error("upload failed")
}

Example (MultipleFields)

Multiple fields can be set, via chaining, or WithFields().

package main

import (
	"github.com/cv/slog"
)

func main() {
	l := slog.New()
	l.WithFields(slog.Fields{
		"user": "Tobi",
		"file": "sloth.png",
		"type": "image/png",
	}).Info("upload")
}

Example (Structured)

Structured logging is supported with fields.

package main

import (
	"github.com/cv/slog"
)

func main() {
	l := slog.New()
	l.WithField("user", "Tobo").Info("logged in")
}

Example (Trace)

Trace can be used to simplify logging of start and completion events, for example an upload which may fail.

package main

import (
	"github.com/cv/slog"
)

func main() {
	var err error
	l := slog.New()
	defer l.Trace(slog.InfoLevel, "upload").Stop(&err)
}

Index

• Variables
• type Entry
  • func NewEntry(log *Logger) *Entry
  • func (e *Entry) Debug(msg string)
  • func (e *Entry) Error(msg string)
  • func (e *Entry) Fatal(msg string)
  • func (e *Entry) IfError(err error) Interface
  • func (e *Entry) Info(msg string)
  • func (e *Entry) Panic(msg string)
  • func (e *Entry) Stop(err *error)
  • func (e *Entry) Trace(level Level, msg string) *Entry
  • func (e *Entry) Warn(msg string)
  • func (e *Entry) WithError(err error) *Entry
  • func (e *Entry) WithField(key string, value interface{}) *Entry
  • func (e *Entry) WithFields(fields Fielder) *Entry
  • func (e *Entry) Writer(level Level) PrefixWriteCloser
• type Fielder
• type Fields
  • func (f Fields) Fields() Fields
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) HandleLog(e *Entry) error
• type Interface
• type Level
  • func ParseLevel(s string, defaultLevel Level) Level
  • func (l Level) MarshalJSON() ([]byte, error)
  • func (l Level) MarshalText() ([]byte, error)
  • func (l *Level) Set(value string) error
  • func (l Level) String() string
  • func (l *Level) UnmarshalText(text []byte) error
• type Logger
  • func New() *Logger
  • func (l *Logger) Debug(msg string)
  • func (l *Logger) Error(msg string)
  • func (l *Logger) Fatal(msg string)
  • func (l *Logger) IfError(err error) Interface
  • func (l *Logger) Info(msg string)
  • func (l *Logger) Panic(msg string)
  • func (l *Logger) RegisterHandler(maxLevel Level, handler Handler) *Logger
  • func (l *Logger) Trace(level Level, msg string) *Entry
  • func (l *Logger) Warn(msg string)
  • func (l *Logger) WithError(err error) *Entry
  • func (l *Logger) WithField(key string, value interface{}) *Entry
  • func (l *Logger) WithFields(fields Fielder) *Entry
  • func (l *Logger) Writer(level Level) PrefixWriteCloser
• type PrefixWriteCloser

Examples

• Package (Errors)
• Package (MultipleFields)
• Package (Structured)
• Package (Trace)

Variables

var Nil = &Logger{}

Nil logger that satisfies zlog.Interface but sends all messages to the bit bucket

Types

type Entry

type Entry struct {
	Logger  *Logger   `json:"-"`
	Fields  Fields    `json:"fields"`
	Level   Level     `json:"level"`
	Time    time.Time `json:"time"`
	Message string    `json:"msg"`
	// contains filtered or unexported fields
}

Entry represents a single log entry.

func NewEntry

func NewEntry(log *Logger) *Entry

NewEntry returns a new entry for `log`.

func (*Entry) Debug

func (e *Entry) Debug(msg string)

Debug level message.

func (*Entry) Error

func (e *Entry) Error(msg string)

Error level message.

func (*Entry) Fatal

func (e *Entry) Fatal(msg string)

Fatal level message, followed by an exit.

func (*Entry) IfError

func (e *Entry) IfError(err error) Interface

IfError returns an Interface that will only log if err is not nil

func (*Entry) Info

func (e *Entry) Info(msg string)

Info level message.

func (*Entry) Panic

func (e *Entry) Panic(msg string)

Panic level message, followed by a panic.

func (*Entry) Stop

func (e *Entry) Stop(err *error)

Stop should be used with Trace, to fire off the completion message. When an `err` is passed the "error" field is set, and the log level is error.

func (*Entry) Trace

func (e *Entry) Trace(level Level, msg string) *Entry

Trace returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.

func (*Entry) Warn

func (e *Entry) Warn(msg string)

Warn level message.

func (*Entry) WithError

func (e *Entry) WithError(err error) *Entry

WithError returns a new entry with the "error" set to `err`.

func (*Entry) WithField

func (e *Entry) WithField(key string, value interface{}) *Entry

WithField returns a new entry with the `key` and `value` set.

func (*Entry) WithFields

func (e *Entry) WithFields(fields Fielder) *Entry

WithFields returns a new entry with `fields` set.

func (*Entry) Writer

func (e *Entry) Writer(level Level) PrefixWriteCloser

Writer returns an io.WriteCloser where each line written to that writer will be printed using the handlers for the given Level. It is the caller's responsibility to close it.

type Fielder

type Fielder interface {
	Fields() Fields
}

Fielder is an interface for providing fields to custom types.

type Fields

type Fields map[string]interface{}

Fields represents a map of entry level data used for structured logging.

func (Fields) Fields

func (f Fields) Fields() Fields

Fields implements Fielder.

type Handler

type Handler interface {
	HandleLog(*Entry) error
}

Handler is used to handle log events, outputting them to stdio or sending them to remote services. See the "handlers" directory for implementations.

It is left up to Handlers to implement thread-safety.

type HandlerFunc

type HandlerFunc func(*Entry) error

The HandlerFunc type is an adapter to allow the use of ordinary functions as log handlers. If f is a function with the appropriate signature, HandlerFunc(f) is a Handler object that calls f.

func (HandlerFunc) HandleLog

func (f HandlerFunc) HandleLog(e *Entry) error

HandleLog calls f(e).

type Interface

type Interface interface {
	WithFields(fields Fielder) *Entry
	WithField(key string, value interface{}) *Entry
	WithError(err error) *Entry
	Debug(msg string)
	Info(msg string)
	Warn(msg string)
	Error(msg string)
	Fatal(msg string)
	Panic(msg string)
	IfError(error) Interface
	Trace(level Level, msg string) *Entry
	Writer(level Level) PrefixWriteCloser
}

Interface represents the API of both Logger and Entry.

type Level

type Level int

Level of severity.

const (
	PanicLevel Level = iota
	FatalLevel
	ErrorLevel
	WarnLevel
	InfoLevel
	DebugLevel
)

Log levels.

func ParseLevel

func ParseLevel(s string, defaultLevel Level) Level

ParseLevel parses level string.

func (Level) MarshalJSON

func (l Level) MarshalJSON() ([]byte, error)

MarshalJSON returns the level string.

func (Level) MarshalText

func (l Level) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler

func (*Level) Set

func (l *Level) Set(value string) error

Set implements cli.Generic

func (Level) String

func (l Level) String() string

String implements io.Stringer.

func (*Level) UnmarshalText

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

UnmarshalText implements encoding.TextUnmarshaler

type Logger

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

Logger represents a logger. It will not do anything useful unless a handler has been registered with RegisterHandler.

func New

func New() *Logger

New allocates a new Logger.

func (*Logger) Debug

func (l *Logger) Debug(msg string)

Debug level message.

func (*Logger) Error

func (l *Logger) Error(msg string)

Error level message.

func (*Logger) Fatal

func (l *Logger) Fatal(msg string)

Fatal level message, followed by an exit.

func (*Logger) IfError

func (l *Logger) IfError(err error) Interface

IfError returns an Interface that will only log if err is not nil

func (*Logger) Info

func (l *Logger) Info(msg string)

Info level message.

func (*Logger) Panic

func (l *Logger) Panic(msg string)

Panic level message, followed by a panic.

func (*Logger) RegisterHandler

func (l *Logger) RegisterHandler(maxLevel Level, handler Handler) *Logger

RegisterHandler adds a new Handler and specifies the maximum Level that the handler will be passed log entries for

func (*Logger) Trace

func (l *Logger) Trace(level Level, msg string) *Entry

Trace returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.

func (*Logger) Warn

func (l *Logger) Warn(msg string)

Warn level message.

func (*Logger) WithError

func (l *Logger) WithError(err error) *Entry

WithError returns a new entry with the "error" set to `err`.

func (*Logger) WithField

func (l *Logger) WithField(key string, value interface{}) *Entry

WithField returns a new entry with the `key` and `value` set.

func (*Logger) WithFields

func (l *Logger) WithFields(fields Fielder) *Entry

WithFields returns a new entry with `fields` set.

func (*Logger) Writer

func (l *Logger) Writer(level Level) PrefixWriteCloser

Writer returns an io.WriteCloser where each line written to that writer will be printed using the handlers for the given Level. It is the caller's responsibility to close it.

type PrefixWriteCloser

type PrefixWriteCloser interface {
	io.WriteCloser
	Prefix(prefix string) PrefixWriteCloser
}

PrefixWriteCloser is an io.WriteCloser that can be prefixed for every line it writes