log: github.com/apex/log Index | Examples | Files | Directories

package log

import "github.com/apex/log"

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.

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

Code:

err := errors.New("boom")
log.WithError(err).Error("upload failed")

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

Code:

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

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

Code:

log.WithField("user", "Tobo").Info("logged in")

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

Code:

defer log.Trace("upload").Stop(&err)
return nil

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

Code:

log.Infof("%s logged in", "Tobi")

Index

Examples

Package Files

default.go doc.go entry.go interface.go levels.go logger.go pkg.go stack.go

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 Uses

func Debug(msg string)

Debug level message.

func Debugf Uses

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

Debugf level formatted message.

func Error Uses

func Error(msg string)

Error level message.

func Errorf Uses

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

Errorf level formatted message.

func Fatal Uses

func Fatal(msg string)

Fatal level message, followed by an exit.

func Fatalf Uses

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

Fatalf level formatted message, followed by an exit.

func Info Uses

func Info(msg string)

Info level message.

func Infof Uses

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

Infof level formatted message.

func SetHandler Uses

func SetHandler(h Handler)

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

func SetLevel Uses

func SetLevel(l Level)

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

func SetLevelFromString Uses

func SetLevelFromString(s string)

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

func Warn Uses

func Warn(msg string)

Warn level message.

func Warnf Uses

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

Warnf level formatted message.

type Entry Uses

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 Uses

func NewEntry(log *Logger) *Entry

NewEntry returns a new entry for `log`.

func Trace Uses

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 WithError Uses

func WithError(err error) *Entry

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

func WithField Uses

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

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

func WithFields Uses

func WithFields(fields Fielder) *Entry

WithFields returns a new entry with `fields` set.

func (*Entry) Debug Uses

func (e *Entry) Debug(msg string)

Debug level message.

func (*Entry) Debugf Uses

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

Debugf level formatted message.

func (*Entry) Error Uses

func (e *Entry) Error(msg string)

Error level message.

func (*Entry) Errorf Uses

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

Errorf level formatted message.

func (*Entry) Fatal Uses

func (e *Entry) Fatal(msg string)

Fatal level message, followed by an exit.

func (*Entry) Fatalf Uses

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

Fatalf level formatted message, followed by an exit.

func (*Entry) Info Uses

func (e *Entry) Info(msg string)

Info level message.

func (*Entry) Infof Uses

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

Infof level formatted message.

func (*Entry) Stop Uses

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 Uses

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 Uses

func (e *Entry) Warn(msg string)

Warn level message.

func (*Entry) Warnf Uses

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

Warnf level formatted message.

func (*Entry) WithError Uses

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 Uses

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

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

func (*Entry) WithFields Uses

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

WithFields returns a new entry with `fields` set.

type Fielder Uses

type Fielder interface {
    Fields() Fields
}

Fielder is an interface for providing fields to custom types.

type Fields Uses

type Fields map[string]interface{}

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

func (Fields) Fields Uses

func (f Fields) Fields() Fields

Fields implements Fielder.

func (Fields) Get Uses

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

Get field value by name.

func (Fields) Names Uses

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

Names returns field names sorted.

type Handler Uses

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 Uses

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 Uses

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

HandleLog calls f(e).

type Interface Uses

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)
    Debugf(msg string, v ...interface{})
    Infof(msg string, v ...interface{})
    Warnf(msg string, v ...interface{})
    Errorf(msg string, v ...interface{})
    Fatalf(msg string, v ...interface{})
    Trace(msg string) *Entry
}

Interface represents the API of both Logger and Entry.

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

singletons ftw?

type Level Uses

type Level int

Level of severity.

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

Log levels.

func MustParseLevel Uses

func MustParseLevel(s string) Level

MustParseLevel parses level string or panics.

func ParseLevel Uses

func ParseLevel(s string) (Level, error)

ParseLevel parses level string.

func (Level) MarshalJSON Uses

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

MarshalJSON implementation.

func (Level) String Uses

func (l Level) String() string

String implementation.

func (*Level) UnmarshalJSON Uses

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

UnmarshalJSON implementation.

type Logger Uses

type Logger struct {
    Handler Handler
    Level   Level
}

Logger represents a logger with configurable Level and Handler.

func (*Logger) Debug Uses

func (l *Logger) Debug(msg string)

Debug level message.

func (*Logger) Debugf Uses

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

Debugf level formatted message.

func (*Logger) Error Uses

func (l *Logger) Error(msg string)

Error level message.

func (*Logger) Errorf Uses

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

Errorf level formatted message.

func (*Logger) Fatal Uses

func (l *Logger) Fatal(msg string)

Fatal level message, followed by an exit.

func (*Logger) Fatalf Uses

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

Fatalf level formatted message, followed by an exit.

func (*Logger) Info Uses

func (l *Logger) Info(msg string)

Info level message.

func (*Logger) Infof Uses

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

Infof level formatted message.

func (*Logger) Trace Uses

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 Uses

func (l *Logger) Warn(msg string)

Warn level message.

func (*Logger) Warnf Uses

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

Warnf level formatted message.

func (*Logger) WithError Uses

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

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

func (*Logger) WithField Uses

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 Uses

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

WithFields returns a new entry with `fields` set.

Directories

PathSynopsis
handlers/cliPackage cli implements a colored text handler suitable for command-line interfaces.
handlers/deltaPackage delta provides a log handler which times the delta between each log call, useful for debug output for command-line programs.
handlers/discardPackage discard implements a no-op handler useful for benchmarks and tests.
handlers/esPackage es implements an Elasticsearch batch handler.
handlers/graylogPackage implements a Graylog-backed handler.
handlers/jsonPackage json implements a JSON handler.
handlers/kinesis
handlers/levelPackage level implements a level filter handler.
handlers/logfmtPackage logfmt implements a "logfmt" format handler.
handlers/memoryPackage memory implements an in-memory handler useful for testing, as the entries can be accessed after writes.
handlers/multiPackage multi implements a handler which invokes a number of handlers.
handlers/papertrailPackage papertrail implements a papertrail logfmt format handler.
handlers/textPackage text implements a development-friendly textual handler.

Package log imports 9 packages (graph) and is imported by 736 packages. Updated 2018-10-11. Refresh now. Tools for package owners.