README
¶
Go logging library. Canonical import path: zgo.at/zlog. You will need Go 1.11
or newer.
The main goal is to offer a friendly and ergonomic API.
Getting the maximum possible amount of performance or zero-allocations are not goals, although simple benchmarks show it should be more than Fast Enough™ for most purposes (if not, there are a few max-performance libraries already).
Usage
Basics:
zlog.Print("foo") // 15:55:17 foo
zlog.Printf("foo %d", 1) // 15:55:17 foo 1
zlog.Error(err) // 15:55:17 oh noes
zlog.Errorf("foo %d", 1) // 15:55:17 foo 1
This does what you expect: output a message to stdout or stderr.
You can add module information and fields for extra information:
log := zlog.Module("test")
log.Print("foo") // 15:56:12 test: foo
log = l.Fields(zlog.F{"foo": "bar"})
log.Print("foo") // 15:56:55 test: foo key="val"
Debug logs are printed only for modules marked as debug:
zlog.Module("bar").Debug("w00t") // Prints nothing (didn't enable module "bar").
log := zlog.SetDebug("bar") // Enable debug logs only for module "bar".
log.Module("bar").Debug("w00t") // 15:56:55 w00t
Trace logs are like debug logs, but are also printed when there is an error:
log := zlog.Module("foo")
log.Trace("useful info")
log.Error(err)
log.ResetTrace() // Remove all traces.
This is pretty useful for adding context to errors without clobbering your general log with mostly useless info.
You can also easily record timings; this is printed for modules marked as debug:
log := zlog.SetDebug("long-running").Module("long-running")
time.Sleep(1 * time.Second)
log = log.Since("sleep one") // long-running 11ms sleep one
time.Sleep(20*time.Millisecond)
log.Since("sleep two") // long-running 11ms sleep two
// Add timing as fields, always works regardless of Debug.
log.SinceLog().Print("long-running finshed")
The Recover() helper function makes it easier to recover from panics in
goroutines:
go func() {
defer zlog.Recover() // Recover panics and report with Error().
panic("oh noes!")
}
See GoDoc for the full reference.
Configuration
Configuration is done by setting the Config variable (usually during
initialisation of your app).
It's not possible to configure individual logger instances. It's not often needed, and adds some complexity.
Existing outputs you can use:
- zgo.at/zlog_sentry – send errors to Sentry.
Documentation
¶
Overview ¶
Package zlog is a logging library.
Index ¶
- Constants
- func Error(err error)
- func Errorf(f string, v ...interface{})
- func Print(v ...interface{})
- func Printf(f string, v ...interface{})
- func ProfileCPU(path string) func()
- func ProfileHeap(path string)
- func Recover(cb ...func(Log) Log)
- type ConfigT
- type F
- type Log
- func (l Log) Context(ctx context.Context)
- func (l Log) Debug(v ...interface{})
- func (l Log) Debugf(f string, v ...interface{})
- func (l Log) Error(err error)
- func (l Log) Errorf(f string, v ...interface{})
- func (l Log) Field(k string, v interface{}) Log
- func (l Log) Fields(f F) Log
- func (l Log) FieldsLocation() Log
- func (l Log) FieldsRequest(r *http.Request) Log
- func (l Log) FieldsSince() Log
- func (l Log) Module(m string) Log
- func (l Log) Print(v ...interface{})
- func (l Log) Printf(f string, v ...interface{})
- func (l Log) ResetTrace()
- func (l Log) SetDebug(m ...string) Log
- func (l Log) Since(msg string) Log
- func (l Log) Trace(v ...interface{}) Log
- func (l Log) Tracef(f string, v ...interface{}) Log
- type OutputFunc
Constants ¶
const ( LevelInfo = 0 LevelErr = 1 LevelDbg = 2 LevelTrace = 3 )
Log levels.
Variables ¶
This section is empty.
Functions ¶
func ProfileCPU ¶
func ProfileCPU(path string) func()
ProfileCPU writes a memory if the path is non-empty.
This should be called on start and the returned function on end (e.g. defer).
func ProfileHeap ¶
func ProfileHeap(path string)
ProfileHeap writes a memory if the path is non-empty. This is usually called just before the program exits.
func Recover ¶
Recover from a panic.
Any panics will be recover()'d and reported with Error():
go func() {
defer zlog.Recover()
// ... do work...
}()
The first callback will be called before the Error() call, and can be used to modify the Log instance, for example to add fields:
defer zlog.Recover(func(l Log) Log {
return l.Fields(zlog.F{"id": id})
})
Any other callbacks will be called after the Error() call. Modifying the Log instance has no real use.
Types ¶
type ConfigT ¶
type ConfigT struct {
// Outputs for a Log entry.
//
// The default is to print to stderr for errors, and stdout for everything
// else. Generally you want to keep this as a backup and add other
// additional outputs, for example:
//
// zlog.Config.Outputs = append(zlog.Config.Outputs, func(l Log) {
// if l.Level != LevelErr { // Only process errors.
// return
// }
//
// // .. send to external error notification service ..
// })
//
// zlog.Config.Outputs = append(zlog.Config.Outputs, func(l Log) {
// if l.Level == LevelErr { // Only process non-errors.
// return
// }
//
// // .. send to external logging service ..
// })
Outputs []OutputFunc
// Filter stack traces, only used if the error is a github.com/pkg/errors
// with a stack trace.
// Useful to filter out HTTP middleware and other useless stuff.
StackFilter *errorutil.Patterns
// Global debug modules; always print debug information for these.
//
// Debug information will be printed for all modules if "all" is in the
// list.
Debug []string
// Format function used by the default stdout/stderr output. This takes a
// Log entry and formats it for output.
Format func(Log) string
// Time/date format as accepted by time.Format(); used in the default
// Format() function.
//
// The default is to just print the time, which works well in development.
// For production you probably want to use time.RFC3339 or some such.
//
// This is used in the standard format() function, not not elsewhere.
FmtTime string
}
ConfigT is the configuration struct.
var Config ConfigT
Config for this package.
func (ConfigT) RunOutputs ¶
type Log ¶
type Log struct {
Ctx context.Context
Msg string // Log message; set with Print(), Debug(), etc.
Err error // Original error, set with Error().
Level int // 0: print, 1: err, 2: debug, 3: trace
Modules []string // Modules added to the logger.
Data F // Fields added to the logger.
DebugModules []string // List of modules to debug.
Traces []string // Traces added to the logger.
// contains filtered or unexported fields
}
Log module.
func FieldsRequest ¶
FieldsRequest adds information from a HTTP request as fields.
func (Log) Context ¶
Context adds a context to the Log entry.
This isn't used by zlog, and mostly so that outputs can use it if needed.
func (Log) Debug ¶
func (l Log) Debug(v ...interface{})
Debug records debugging information. This won't do anything if the current module isn't beind debugged.
func (Log) Debugf ¶
Debugf records debugging information. This won't do anything if the current module isn't beind debugged.
func (Log) FieldsLocation ¶
FieldsLocation records the caller location.
func (Log) FieldsRequest ¶
FieldsRequest adds information from a HTTP request as fields.
func (Log) FieldsSince ¶
FieldsSince adds timing information recorded with Since as fields.
func (Log) ResetTrace ¶
func (l Log) ResetTrace()
ResetTrace removes all trace logs added with Trace() and Tracef().
type OutputFunc ¶
type OutputFunc func(Log)
OutputFunc is an output function, used in Config.Outputs.
Source Files