Back to godoc.org
github.com/apex/log

Package log

v1.9.0
Latest Go to latest

The latest major version is .

Published: Aug 18, 2020 | License: MIT | Module: github.com/apex/log

Overview

Package log implements a simple structured logging API designed with few assumptions. Designed for centralized logging solutions such as Kinesis which require encoding and decoding before fanning-out to handlers.

You may use this package with inline handlers, much like Logrus, however a centralized solution is recommended so that apps do not need to be re-deployed to add or remove logging service providers.

Example (Errors)

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

Code:

package main

import (
	"errors"
	"github.com/apex/log"
)

func main() {
	err := errors.New("boom")
	log.WithError(err).Error("upload failed")
}
Example (MultipleFields)

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

Code:

package main

import (
	"github.com/apex/log"
)

func main() {
	log.WithFields(log.Fields{
		"user": "Tobi",
		"file": "sloth.png",
		"type": "image/png",
	}).Info("upload")
}
Example (Structured)

Structured logging is supported with fields, and is recommended over the formatted message variants.

Code:

package main

import (
	"github.com/apex/log"
)

func main() {
	log.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.

Code:

package main

import (
	"github.com/apex/log"
)

func main() (err error) {
	defer log.Trace("upload").Stop(&err)
	return nil
}
Example (Unstructured)

Unstructured logging is supported, but not recommended since it is hard to query.

Code:

package main

import (
	"github.com/apex/log"
)

func main() {
	log.Infof("%s logged in", "Tobi")
}

Index

Examples

Variables

var ErrInvalidLevel = errors.New("invalid level")

ErrInvalidLevel is returned if the severity level is invalid.

var Now = time.Now

Now returns the current time.

func Debug

func Debug(msg string)

Debug level message.

func Debugf

func Debugf(msg string, v ...interface{})

Debugf level formatted message.

func Error

func Error(msg string)

Error level message.

func Errorf

func Errorf(msg string, v ...interface{})

Errorf level formatted message.

func Fatal

func Fatal(msg string)

Fatal level message, followed by an exit.

func Fatalf

func Fatalf(msg string, v ...interface{})

Fatalf level formatted message, followed by an exit.

func Info

func Info(msg string)

Info level message.

func Infof

func Infof(msg string, v ...interface{})

Infof level formatted message.

func NewContext

func NewContext(ctx context.Context, v Interface) context.Context

NewContext returns a new context with logger.

func SetHandler

func SetHandler(h Handler)

SetHandler sets the handler. This is not thread-safe. The default handler outputs to the stdlib log.

func SetLevel

func SetLevel(l Level)

SetLevel sets the log level. This is not thread-safe.

func SetLevelFromString

func SetLevelFromString(s string)

SetLevelFromString sets the log level from a string, panicing when invalid. This is not thread-safe.

func Warn

func Warn(msg string)

Warn level message.

func Warnf

func Warnf(msg string, v ...interface{})

Warnf level formatted message.

type Entry

type Entry struct {
	Logger    *Logger   `json:"-"`
	Fields    Fields    `json:"fields"`
	Level     Level     `json:"level"`
	Timestamp time.Time `json:"timestamp"`
	Message   string    `json:"message"`
	// 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 Trace

func Trace(msg string) *Entry

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

func WithDuration

func WithDuration(d time.Duration) *Entry

WithDuration returns a new entry with the "duration" field set to the given duration in milliseconds.

func WithError

func WithError(err error) *Entry

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

func WithField

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

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

func WithFields

func WithFields(fields Fielder) *Entry

WithFields returns a new entry with `fields` set.

func (*Entry) Debug

func (e *Entry) Debug(msg string)

Debug level message.

func (*Entry) Debugf

func (e *Entry) Debugf(msg string, v ...interface{})

Debugf level formatted message.

func (*Entry) Error

func (e *Entry) Error(msg string)

Error level message.

func (*Entry) Errorf

func (e *Entry) Errorf(msg string, v ...interface{})

Errorf level formatted message.

func (*Entry) Fatal

func (e *Entry) Fatal(msg string)

Fatal level message, followed by an exit.

func (*Entry) Fatalf

func (e *Entry) Fatalf(msg string, v ...interface{})

Fatalf level formatted message, followed by an exit.

func (*Entry) Info

func (e *Entry) Info(msg string)

Info level message.

func (*Entry) Infof

func (e *Entry) Infof(msg string, v ...interface{})

Infof level formatted message.

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(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) Warnf

func (e *Entry) Warnf(msg string, v ...interface{})

Warnf level formatted message.

func (*Entry) WithDuration

func (e *Entry) WithDuration(d time.Duration) *Entry

WithDuration returns a new entry with the "duration" field set to the given duration in milliseconds.

func (*Entry) WithError

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

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

The given error may implement .Fielder, if it does the method will add all its `.Fields()` into the returned entry.

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.

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.

func (Fields) Get

func (f Fields) Get(name string) interface{}

Get field value by name.

func (Fields) Names

func (f Fields) Names() (v []string)

Names returns field names sorted.

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(Fielder) *Entry
	WithField(string, interface{}) *Entry
	WithDuration(time.Duration) *Entry
	WithError(error) *Entry
	Debug(string)
	Info(string)
	Warn(string)
	Error(string)
	Fatal(string)
	Debugf(string, ...interface{})
	Infof(string, ...interface{})
	Warnf(string, ...interface{})
	Errorf(string, ...interface{})
	Fatalf(string, ...interface{})
	Trace(string) *Entry
}

Interface represents the API of both Logger and Entry.

var Log Interface = &Logger{
	Handler: HandlerFunc(handleStdLog),
	Level:   InfoLevel,
}

singletons ftw?

func FromContext

func FromContext(ctx context.Context) Interface

FromContext returns the logger from context, or log.Log.

type Level

type Level int

Level of severity.

const (
	InvalidLevel Level = iota - 1
	DebugLevel
	InfoLevel
	WarnLevel
	ErrorLevel
	FatalLevel
)

Log levels.

func MustParseLevel

func MustParseLevel(s string) Level

MustParseLevel parses level string or panics.

func ParseLevel

func ParseLevel(s string) (Level, error)

ParseLevel parses level string.

func (Level) MarshalJSON

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

MarshalJSON implementation.

func (Level) String

func (l Level) String() string

String implementation.

func (*Level) UnmarshalJSON

func (l *Level) UnmarshalJSON(b []byte) error

UnmarshalJSON implementation.

type Logger

type Logger struct {
	Handler Handler
	Level   Level
}

Logger represents a logger with configurable Level and Handler.

func (*Logger) Debug

func (l *Logger) Debug(msg string)

Debug level message.

func (*Logger) Debugf

func (l *Logger) Debugf(msg string, v ...interface{})

Debugf level formatted message.

func (*Logger) Error

func (l *Logger) Error(msg string)

Error level message.

func (*Logger) Errorf

func (l *Logger) Errorf(msg string, v ...interface{})

Errorf level formatted message.

func (*Logger) Fatal

func (l *Logger) Fatal(msg string)

Fatal level message, followed by an exit.

func (*Logger) Fatalf

func (l *Logger) Fatalf(msg string, v ...interface{})

Fatalf level formatted message, followed by an exit.

func (*Logger) Info

func (l *Logger) Info(msg string)

Info level message.

func (*Logger) Infof

func (l *Logger) Infof(msg string, v ...interface{})

Infof level formatted message.

func (*Logger) Trace

func (l *Logger) Trace(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) Warnf

func (l *Logger) Warnf(msg string, v ...interface{})

Warnf level formatted message.

func (*Logger) WithDuration

func (l *Logger) WithDuration(d time.Duration) *Entry

WithDuration returns a new entry with the "duration" field set to the given duration in milliseconds.

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.

Note that the `key` should not have spaces in it - use camel case or underscores

func (*Logger) WithFields

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

WithFields returns a new entry with `fields` set.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier