README
¶
log
Package log implements a simple structured logging API inspired by Logrus, designed with centralization in mind. Read more on Medium.
Badges
tjholowaychuk.com · GitHub @tj · Twitter @tjholowaychuk
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/francoishill/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/francoishill/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/francoishill/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/francoishill/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/francoishill/log"
)
func main() {
log.Infof("%s logged in", "Tobi")
}
Output:
Index ¶
- func Alert(msg string)
- func Alertf(msg string, v ...interface{})
- func Critical(msg string)
- func Criticalf(msg string, v ...interface{})
- func Debug(msg string)
- func Debugf(msg string, v ...interface{})
- func Emergency(msg string)
- func Emergencyf(msg string, v ...interface{})
- func Error(msg string)
- func Errorf(msg string, v ...interface{})
- func Info(msg string)
- func Infof(msg string, v ...interface{})
- func Notice(msg string)
- func Noticef(msg string, v ...interface{})
- func SetHandler(h Handler)
- func SetLevel(l Level)
- func Warn(msg string)
- func Warnf(msg string, v ...interface{})
- type Entry
- func (e *Entry) Alert(msg string)
- func (e *Entry) Alertf(msg string, v ...interface{})
- func (e *Entry) Critical(msg string)
- func (e *Entry) Criticalf(msg string, v ...interface{})
- func (e *Entry) Debug(msg string)
- func (e *Entry) Debugf(msg string, v ...interface{})
- func (e *Entry) Emergency(msg string)
- func (e *Entry) Emergencyf(msg string, v ...interface{})
- func (e *Entry) Error(msg string)
- func (e *Entry) Errorf(msg string, v ...interface{})
- func (e *Entry) Info(msg string)
- func (e *Entry) Infof(msg string, v ...interface{})
- func (e *Entry) Notice(msg string)
- func (e *Entry) Noticef(msg string, v ...interface{})
- func (e *Entry) Stop(err *error)
- func (e *Entry) StopLevel(level Level, err *error)
- func (e *Entry) Trace(msg string) *Entry
- func (e *Entry) TraceLevel(level Level, msg string) *Entry
- func (e *Entry) Warn(msg string)
- func (e *Entry) Warnf(msg string, v ...interface{})
- 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) Alert(msg string)
- func (l *Logger) Alertf(msg string, v ...interface{})
- func (l *Logger) Critical(msg string)
- func (l *Logger) Criticalf(msg string, v ...interface{})
- func (l *Logger) Debug(msg string)
- func (l *Logger) Debugf(msg string, v ...interface{})
- func (l *Logger) Emergency(msg string)
- func (l *Logger) Emergencyf(msg string, v ...interface{})
- func (l *Logger) Error(msg string)
- func (l *Logger) Errorf(msg string, v ...interface{})
- func (l *Logger) Info(msg string)
- func (l *Logger) Infof(msg string, v ...interface{})
- func (l *Logger) Notice(msg string)
- func (l *Logger) Noticef(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) 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 ¶
This section is empty.
Functions ¶
func Alertf ¶
func Alertf(msg string, v ...interface{})
Alertf level formatted message, followed by an exit.
func Criticalf ¶
func Criticalf(msg string, v ...interface{})
Criticalf level formatted message, followed by an exit.
func Emergencyf ¶
func Emergencyf(msg string, v ...interface{})
Emergencyf level formatted message, followed by an exit.
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 WithFields ¶
WithFields returns a new entry with `fields` set.
func (*Entry) Emergencyf ¶
Emergencyf level formatted message, followed by an exit.
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) StopLevel ¶
StopLevel 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) TraceLevel ¶
TraceLevel returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.
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(fields Fielder) *Entry
WithField(key string, value interface{}) *Entry
WithError(err error) *Entry
Debug(msg string)
Info(msg string)
Notice(msg string)
Warn(msg string)
Error(msg string)
Critical(msg string)
Alert(msg string)
Emergency(msg string)
Debugf(msg string, v ...interface{})
Infof(msg string, v ...interface{})
Noticef(msg string, v ...interface{})
Warnf(msg string, v ...interface{})
Errorf(msg string, v ...interface{})
Criticalf(msg string, v ...interface{})
Alertf(msg string, v ...interface{})
Emergencyf(msg string, v ...interface{})
Trace(msg string) *Entry
}
Interface represents the API of both Logger and Entry as per RFC5424
type Level ¶
type Level int
Level of severity.
const ( DebugLevel Level = iota InfoLevel NoticeLevel WarnLevel ErrorLevel CriticalLevel AlertLevel EmergencyLevel )
Log levels.
func (Level) MarshalJSON ¶
MarshalJSON returns the level string.
type Logger ¶
Logger represents a logger with configurable Level and Handler.
func (*Logger) Emergencyf ¶
Emergencyf level formatted message, followed by an exit.
func (*Logger) Trace ¶
Trace returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.
func (*Logger) WithFields ¶
WithFields returns a new entry with `fields` set.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
_examples
|
|
|
handlers
|
|
|
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. |
|
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. |
|
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. |
|
text
Package text implements a development-friendly textual handler.
|
Package text implements a development-friendly textual handler. |