The highest tagged major version is
README
¶
log
Log is a simple, highly configurable, Structured Logging library
Why another logging library?
There's allot of great stuff out there, but also thought a log library could be made more configurable using per handler log levels.
Features
- Logger is simple, only logic to create the log entry and send it off to the handlers and they take it from there.
- Ability to specify which log levels get sent to each handler
- Built-in console, syslog, http, HipChat, json and email handlers
- Handlers are simple to write + easy to register
- Logger is a singleton ( one of the few instances a singleton is desired ) so the root package registers which handlers are used and any libraries just follow suit.
- Convenient context helpers
GetContext&SetContext - Works with go-playground/errors extracting types and tags when used with
WithError, is the default - Works with pkg/errors when used with
WithError, must set usingSetWithErrFn - Works with segmentio/errors-go extracting types and tags when used with
WithError, must set usingSetWithErrFn
Installation
Use go get
go get -u github.com/go-playground/log
Usage
import the log package, setup at least one handler
package main
import (
"errors"
"github.com/go-playground/log"
"github.com/go-playground/log/handlers/console"
)
func main() {
cLog := console.New(true)
log.AddHandler(cLog, log.AllLevels...)
// Trace
defer log.WithTrace().Info("time to run")
log.Debug("debug")
log.Info("info")
log.Notice("notice")
log.Warn("warn")
log.Error("error")
// log.Panic("panic") // this will panic
log.Alert("alert")
// log.Fatal("fatal") // this will call os.Exit(1)
err := errors.New("the is an error")
// logging with fields can be used with any of the above
log.WithError(err).WithFields(log.F("key", "value")).Info("test info")
// predefined global fields
log.WithDefaultFields(log.Fields{
{"program", "test"},
{"version", "0.1.3"},
}...)
log.WithField("key", "value").Info("testing default fields")
// or request scoped default fields
logger := log.WithFields(
log.F("request", "req"),
log.F("scoped", "sco"),
)
logger.WithField("key", "value").Info("test")
}
Adding your own Handler
package main
import (
"bytes"
"fmt"
"github.com/go-playground/log"
)
// CustomHandler is your custom handler
type CustomHandler struct {
// whatever properties you need
}
// Log accepts log entries to be processed
func (c *CustomHandler) Log(e log.Entry) {
// below prints to os.Stderr but could marshal to JSON
// and send to central logging server
// ---------
// |----------> | console |
// | ---------
// i.e. ----------------- ----------------- Unmarshal ------------- --------
// | app log handler | -- json --> | central log app | -- to -> | log handler | --> | syslog |
// ----------------- ----------------- Entry ------------- --------
// | ---------
// |----------> | DataDog |
// ---------
b := new(bytes.Buffer)
b.Reset()
b.WriteString(e.Message)
for _, f := range e.Fields {
fmt.Fprintf(b, " %s=%v", f.Key, f.Value)
}
fmt.Println(b.String())
}
func main() {
cLog := new(CustomHandler)
log.AddHandler(cLog, log.AllLevels...)
// Trace
defer log.WithTrace().Info("took this long")
log.Debug("debug")
log.Info("info")
log.Notice("notice")
log.Warn("warn")
log.Error("error")
// log.Panic("panic") // this will panic
log.Alert("alert")
// log.Fatal("fatal") // this will call os.Exit(1)
// logging with fields can be used with any of the above
log.WithField("key", "value").Info("test info")
}
Log Level Definitions
DebugLevel - Info useful to developers for debugging the application, not useful during operations.
InfoLevel - Normal operational messages - may be harvested for reporting, measuring throughput, etc. - no action required.
NoticeLevel - Normal but significant condition. Events that are unusual but not error conditions - might be summarized in an email to developers or admins to spot potential problems - no immediate action required.
WarnLevel - Warning messages, not an error, but indication that an error will occur if action is not taken, e.g. file system 85% full - each item must be resolved within a given time.
ErrorLevel - Non-urgent failures, these should be relayed to developers or admins; each item must be resolved within a given time.
PanicLevel - A "panic" condition usually affecting multiple apps/servers/sites. At this level it would usually notify all tech staff on call.
AlertLevel - Action must be taken immediately. Should be corrected immediately, therefore notify staff who can fix the problem. An example would be the loss of a primary ISP connection.
FatalLevel - Should be corrected immediately, but indicates failure in a primary system, an example is a loss of a backup ISP connection. ( same as SYSLOG CRITICAL )
Handlers
Pull requests for new handlers are welcome, please provide test coverage is all I ask.
| Handler | Description | Docs |
|---|---|---|
| console | Allows for log messages to be sent to a any writer, default os.Stderr |  |
| syslog | Allows for log messages to be sent via syslog, includes TLS support. |  |
| http | Allows for log messages to be sent via http. Can use the HTTP handler as a base for creating other handlers requiring http transmission. |  |
| Allows for log messages to be sent via email. |  |
|
| hipchat | Allows for log messages to be sent to a hipchat room. |  |
| json | Allows for log messages to be sent to any wrtier in json format. |  |
Package Versioning
I'm jumping on the vendoring bandwagon, you should vendor this package as I will not be creating different version with gopkg.in like allot of my other libraries.
Why? because my time is spread pretty thin maintaining all of the libraries I have + LIFE, it is so freeing not to worry about it and will help me keep pouring out bigger and better things for you the community.
Benchmarks
NOTE: only putting benchmarks at others request, by no means does the number of allocations make one log library better than another!
go test --bench=. -benchmem=true
goos: darwin
goarch: amd64
pkg: github.com/go-playground/log/benchmarks
BenchmarkLogConsoleTenFieldsParallel-8 2000000 946 ns/op 1376 B/op 16 allocs/op
BenchmarkLogConsoleSimpleParallel-8 5000000 296 ns/op 200 B/op 4 allocs/op
Special Thanks
Special thanks to the following libraries that inspired
Documentation
¶
Index ¶
- Constants
- Variables
- func AddHandler(h Handler, levels ...Level)
- func Alert(v ...interface{})
- func Alertf(s string, v ...interface{})
- func Debug(v ...interface{})
- func Debugf(s string, v ...interface{})
- func Error(v ...interface{})
- func Errorf(s string, v ...interface{})
- func Fatal(v ...interface{})
- func Fatalf(s string, v ...interface{})
- func HandleEntry(e Entry)
- func Info(v ...interface{})
- func Infof(s string, v ...interface{})
- func Notice(v ...interface{})
- func Noticef(s string, v ...interface{})
- func Panic(v ...interface{})
- func Panicf(s string, v ...interface{})
- func SetContext(ctx context.Context, e Entry) context.Context
- func SetExitFunc(fn func(code int))
- func SetWithErrorFn(fn func(Entry, error) Entry)
- func Warn(v ...interface{})
- func Warnf(s string, v ...interface{})
- func WithDefaultFields(fields ...Field)
- type Entry
- func (e Entry) Alert(v ...interface{})
- func (e Entry) Alertf(s string, v ...interface{})
- func (e Entry) Debug(v ...interface{})
- func (e Entry) Debugf(s string, v ...interface{})
- func (e Entry) Error(v ...interface{})
- func (e Entry) Errorf(s string, v ...interface{})
- func (e Entry) Fatal(v ...interface{})
- func (e Entry) Fatalf(s string, v ...interface{})
- func (e Entry) Info(v ...interface{})
- func (e Entry) Infof(s string, v ...interface{})
- func (e Entry) Notice(v ...interface{})
- func (e Entry) Noticef(s string, v ...interface{})
- func (e Entry) Panic(v ...interface{})
- func (e Entry) Panicf(s string, v ...interface{})
- func (e Entry) Warn(v ...interface{})
- func (e Entry) Warnf(s string, v ...interface{})
- func (e Entry) WithError(err error) Entry
- func (e Entry) WithField(key string, value interface{}) Entry
- func (e Entry) WithFields(fields ...Field) Entry
- func (e Entry) WithTrace() Entry
- type Field
- type Fields
- type Handler
- type Level
Constants ¶
const ( // DefaultTimeFormat is the default time format when parsing Time values. // it is exposed to allow handlers to use and not have to redefine DefaultTimeFormat = "2006-01-02T15:04:05.000000000Z07:00" )
Variables ¶
var AllLevels = []Level{ DebugLevel, InfoLevel, NoticeLevel, WarnLevel, ErrorLevel, PanicLevel, AlertLevel, FatalLevel, }
AllLevels is an array of all log levels, for easier registering of all levels to a handler
Functions ¶
func AddHandler ¶
AddHandler adds a new log handler and accepts which log levels that handler will be triggered for
func Alertf ¶
func Alertf(s string, v ...interface{})
Alertf logs an alert log entry with formatting
func Errorf ¶
func Errorf(s string, v ...interface{})
Errorf logs an error log entry with formatting
func HandleEntry ¶
func HandleEntry(e Entry)
HandleEntry handles the log entry and fans out to all handlers with the proper log level This is exposed to allow for centralized logging whereby the log entry is marshalled, passed to a central logging server, unmarshalled and finally fanned out from there.
func Infof ¶
func Infof(s string, v ...interface{})
Infof logs a normal. information, entry with formatiing
func Noticef ¶
func Noticef(s string, v ...interface{})
Noticef logs a notice log entry with formatting
func SetContext ¶
SetContext sets a log entry into the provided context
func SetExitFunc ¶
func SetExitFunc(fn func(code int))
SetExitFunc sets the provided function as the exit function used in Fatal(), Fatalf(), Panic() and Panicf(). This is primarily used when wrapping this library, you can set this to to enable testing (with coverage) of your Fatal() and Fatalf() methods.
func SetWithErrorFn ¶
SetWithErrorFn sets a custom WithError function handlers
func WithDefaultFields ¶
func WithDefaultFields(fields ...Field)
WithDefaultFields adds fields to the underlying logger instance
Types ¶
type Entry ¶
type Entry struct {
Message string `json:"message"`
Timestamp time.Time `json:"timestamp"`
Fields []Field `json:"fields"`
Level Level `json:"level"`
// contains filtered or unexported fields
}
Entry defines a single log entry
func GetContext ¶
GetContext returns the log Entry found in the context, or a new Default log Entry if none is found
func WithFields ¶
WithFields returns a new log entry with the supplied fields appended
func WithTrace ¶
func WithTrace() Entry
WithTrace withh add duration of how long the between this function call and the susequent log
func (Entry) WithFields ¶
WithFields returns a new log entry with the supplied fields appended
type Field ¶
type Field struct {
Key string `json:"key"`
Value interface{} `json:"value"`
}
Field is a single Field key and value
type Handler ¶
type Handler interface {
Log(Entry)
}
Handler is an interface that log handlers need to comply with
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
_examples
|
|
|
errors
|
|
|
handlers
|
|
|
console
Package console allows for log messages to be sent to a any writer, default os.Stderr.
|
Package console allows for log messages to be sent to a any writer, default os.Stderr. |
|
email
Package email allows for log messages to be sent via email.
|
Package email allows for log messages to be sent via email. |
|
http
Package http allows for log messages to be sent via http.
|
Package http allows for log messages to be sent via http. |
|
http/hipchat
Package hipchat allows for log messages to be sent to a hipchat room.
|
Package hipchat allows for log messages to be sent to a hipchat room. |
|
json
Package json implements a JSON handler.
|
Package json implements a JSON handler. |
|
syslog
Package syslog allows for log messages to be sent via syslog.
|
Package syslog allows for log messages to be sent via syslog. |