README
¶
Package log implements a simple structured logging API inspired by Logrus, designed with centralization in mind. Read more on Medium.
Handlers
- apexlogs – handler for Apex Logs
- cli – human-friendly CLI output
- discard – discards all logs
- es – Elasticsearch handler
- graylog – Graylog handler
- json – JSON output handler
- kinesis – AWS Kinesis handler
- level – level filter handler
- logfmt – logfmt plain-text formatter
- memory – in-memory handler for tests
- multi – fan-out to multiple handlers
- papertrail – Papertrail handler
- text – human-friendly colored output
- delta – outputs the delta between log calls and spinner
Example
Example using the Apex Logs handler.
package main
import (
"errors"
"time"
"github.com/apex/log"
)
func main() {
ctx := log.WithFields(log.Fields{
"file": "something.png",
"type": "image/png",
"user": "tobi",
})
for range time.Tick(time.Millisecond * 200) {
ctx.Info("upload")
ctx.Info("upload complete")
ctx.Warn("upload retry")
ctx.WithError(errors.New("unauthorized")).Error("upload failed")
ctx.Errorf("failed to upload %s", "img.png")
}
}
Documentation
¶
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.
package main
import (
"errors"
"github.com/apex/log"
)
func main() {
err := errors.New("boom")
log.WithError(err).Error("upload failed")
}
Output:
Example (MultipleFields) ¶
Multiple fields can be set, via chaining, or WithFields().
package main
import (
"github.com/apex/log"
)
func main() {
log.WithFields(log.Fields{
"user": "Tobi",
"file": "sloth.png",
"type": "image/png",
}).Info("upload")
}
Output:
Example (Structured) ¶
Structured logging is supported with fields, and is recommended over the formatted message variants.
package main
import (
"github.com/apex/log"
)
func main() {
log.WithField("user", "Tobo").Info("logged in")
}
Output:
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/apex/log"
)
func main() (err error) {
defer log.Trace("upload").Stop(&err)
return nil
}
Output:
Example (Unstructured) ¶
Unstructured logging is supported, but not recommended since it is hard to query.
package main
import (
"github.com/apex/log"
)
func main() {
log.Infof("%s logged in", "Tobi")
}
Output:
Index ¶
- Variables
- func Debug(msg string)
- func Debugf(msg string, v ...interface{})
- func Error(msg string)
- func Errorf(msg string, v ...interface{})
- func Fatal(msg string)
- func Fatalf(msg string, v ...interface{})
- func Info(msg string)
- func Infof(msg string, v ...interface{})
- func NewContext(ctx context.Context, v Interface) context.Context
- func SetHandler(h Handler)
- func SetLevel(l Level)
- func SetLevelFromString(s string)
- func Warn(msg string)
- func Warnf(msg string, v ...interface{})
- type Entry
- func (e *Entry) Debug(msg string)
- func (e *Entry) Debugf(msg string, v ...interface{})
- func (e *Entry) Error(msg string)
- func (e *Entry) Errorf(msg string, v ...interface{})
- func (e *Entry) Fatal(msg string)
- func (e *Entry) Fatalf(msg string, v ...interface{})
- func (e *Entry) Info(msg string)
- func (e *Entry) Infof(msg string, v ...interface{})
- func (e *Entry) Stop(err *error)
- func (e *Entry) Trace(msg string) *Entry
- func (e *Entry) Warn(msg string)
- func (e *Entry) Warnf(msg string, v ...interface{})
- func (e *Entry) WithDuration(d time.Duration) *Entry
- func (e *Entry) WithError(err error) *Entry
- func (e *Entry) WithField(key string, value interface{}) *Entry
- func (e *Entry) WithFields(fields Fielder) *Entry
- type Fielder
- type Fields
- type Handler
- type HandlerFunc
- type Interface
- type Level
- type Logger
- func (l *Logger) Debug(msg string)
- func (l *Logger) Debugf(msg string, v ...interface{})
- func (l *Logger) Error(msg string)
- func (l *Logger) Errorf(msg string, v ...interface{})
- func (l *Logger) Fatal(msg string)
- func (l *Logger) Fatalf(msg string, v ...interface{})
- func (l *Logger) Info(msg string)
- func (l *Logger) Infof(msg string, v ...interface{})
- func (l *Logger) Trace(msg string) *Entry
- func (l *Logger) Warn(msg string)
- func (l *Logger) Warnf(msg string, v ...interface{})
- func (l *Logger) WithDuration(d time.Duration) *Entry
- func (l *Logger) WithError(err error) *Entry
- func (l *Logger) WithField(key string, value interface{}) *Entry
- func (l *Logger) WithFields(fields Fielder) *Entry
Examples ¶
Constants ¶
This section is empty.
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.
Functions ¶
func Fatalf ¶
func Fatalf(msg string, v ...interface{})
Fatalf level formatted message, followed by an exit.
func NewContext ¶ added in v1.2.0
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 SetLevelFromString ¶
func SetLevelFromString(s string)
SetLevelFromString sets the log level from a string, panicing when invalid. This is not thread-safe.
Types ¶
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 Trace ¶
Trace returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.
func WithDuration ¶ added in v1.9.0
WithDuration returns a new entry with the "duration" field set to the given duration in milliseconds.
func WithFields ¶
WithFields returns a new entry with `fields` set.
func (*Entry) Stop ¶
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 ¶
Trace returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.
func (*Entry) WithDuration ¶ added in v1.9.0
WithDuration returns a new entry with the "duration" field set to the given duration in milliseconds.
func (*Entry) WithError ¶
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) WithFields ¶
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.
type Handler ¶
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 ¶
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.
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 ¶ added in v1.2.0
FromContext returns the logger from context, or log.Log.
type Level ¶
type Level int
Level of severity.
Log levels.
func MustParseLevel ¶
MustParseLevel parses level string or panics.
func (*Level) UnmarshalJSON ¶
UnmarshalJSON implementation.
type Logger ¶
Logger represents a logger with configurable Level and Handler.
func (*Logger) Trace ¶
Trace returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.
func (*Logger) WithDuration ¶ added in v1.9.0
WithDuration returns a new entry with the "duration" field set to the given duration in milliseconds.
func (*Logger) WithField ¶
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 ¶
WithFields returns a new entry with `fields` set.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
_examples
|
|
|
handlers
|
|
|
apexlogs
Package apexlogs implements a handler for Apex Logs https://apex.sh/logs/.
|
Package apexlogs implements a handler for Apex Logs https://apex.sh/logs/. |
|
cli
Package cli implements a colored text handler suitable for command-line interfaces.
|
Package cli implements a colored text handler suitable for command-line interfaces. |
|
delta
Package delta provides a log handler which times the delta between each log call, useful for debug output for command-line programs.
|
Package delta provides a log handler which times the delta between each log call, useful for debug output for command-line programs. |
|
discard
Package discard implements a no-op handler useful for benchmarks and tests.
|
Package discard implements a no-op handler useful for benchmarks and tests. |
|
es
Package es implements an Elasticsearch batch handler.
|
Package es implements an Elasticsearch batch handler. |
|
graylog
Package implements a Graylog-backed handler.
|
Package implements a Graylog-backed handler. |
|
json
Package json implements a JSON handler.
|
Package json implements a JSON handler. |
|
level
Package level implements a level filter handler.
|
Package level implements a level filter handler. |
|
logfmt
Package logfmt implements a "logfmt" format handler.
|
Package logfmt implements a "logfmt" format handler. |
|
memory
Package memory implements an in-memory handler useful for testing, as the entries can be accessed after writes.
|
Package memory implements an in-memory handler useful for testing, as the entries can be accessed after writes. |
|
multi
Package multi implements a handler which invokes a number of handlers.
|
Package multi implements a handler which invokes a number of handlers. |
|
papertrail
Package papertrail implements a papertrail logfmt format handler.
|
Package papertrail implements a papertrail logfmt format handler. |
|
text
Package text implements a development-friendly textual handler.
|
Package text implements a development-friendly textual handler. |