README
¶
Blammo
This is a simple console logger for Go which supports:
- High performance logging (zero allocations)
- An API modeled on zerolog
- Human readable output, not JSON
- Logging errors to stderr and everything else to stdout
- Optional logging to files
- Not much code
I liked zerolog's API and speed, but its console logging was slow, it lacked stdout/stderr separation, and it was a lot of code -- mostly because it implemented lots of functionality I didn't need.
If you want to log to systemd, JSON APIs or binary files, use zerolog. If you just want logging for humans at high speed with minimal code, this is a smaller and faster option.
Simple usage:
import "github.com/lpar/blammo/log"
// turn on debug output for default logger at runtime
log.SetDebug(true)
log.Info().Msg("Hello sailor")
log.Debug().Int("x", 6).Msg("Debug info")
Hopefully you'll agree that it's better than bad, it's good.
Design notes
I believe in minimizing the number of logging levels. Over many years, these are the ones I've found I use:
- Info: Normal information, progress messages, job output.
- Error: Something has definitely gone wrong.
- Warning: Something has happened which may be a program error or may be a human error, and could be worth investigating.
- Debug: Trace information to be turned on when debugging.
An example of a situation where a warning is appropriate might be an invalid digital signature on a JSON Web Token. It could indicate an error in the decoding, but it could also be caused by someone trying to bypass security using a JWT with a fake signature.
There's no Fatal level in my world, because it's almost never appropriate to crash out in an uncontrolled fashion after detecting an error. If you're in one of the situations where it is appropriate, just do something like:
log.Error().Msg("fatal error")
log.Close()
os.Exit(1)
Errors and warnings are sent to a separate stream by default because that's the Unix convention since time immemorial. Also, on the cloud hosting I use, output to stderr gets highlighted to distinguish it from normal logging output. I'm aware that you can't reliably reconstruct the message sequence from stderr and stdout when they're separated like this; that's why we have timestamps on every line, right?
I haven't implemented the whole zerolog API. For example, if you want to dump
out a slice or array of anything other than a few bytes, you'll have to write a
loop,as there's no equivalent of zerolog's Array type. I think this makes sense
from the point of view of line length and simplicity. I also haven't
implemented special message appenders for types which are Stringers, such as IP
addresses; just use their .String() method.
An added option zerolog lacks is the Msgf() method. This works like
fmt.Printf, and is consequently relatively slow, but is there to make it easy
to migrate code from other loggers that use a Printf-style interface (like my
own first cut at a logging wrapper. It's also
convenient for user-visible error messages where speed isn't a major concern.
Documentation
¶
Index ¶
- type Event
- func (e *Event) Bool(key string, value bool) *Event
- func (e *Event) Bytes(key string, value []byte) *Event
- func (e *Event) Caller() *Event
- func (e *Event) Err(err error) *Event
- func (e *Event) Float32(key string, f float32) *Event
- func (e *Event) Float64(key string, f float64) *Event
- func (e *Event) Int(key string, value int) *Event
- func (e *Event) Int16(key string, value int16) *Event
- func (e *Event) Int32(key string, value int32) *Event
- func (e *Event) Int64(key string, value int64) *Event
- func (e *Event) Int8(key string, value int8) *Event
- func (e *Event) Line() *Event
- func (e *Event) Msg(msg string)
- func (e *Event) Msgf(fmtstr string, vals ...interface{})
- func (e *Event) Str(key string, value string) *Event
- func (e *Event) Time(key string, value time.Time) *Event
- func (e *Event) Uint16(key string, value uint16) *Event
- func (e *Event) Uint32(key string, value uint32) *Event
- func (e *Event) Uint64(key string, value uint64) *Event
- func (e *Event) Uint8(key string, value uint8) *Event
- type Logger
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
// contains filtered or unexported fields
}
Event represents the text collected for output to a given log Writer
func (*Event) Bytes ¶
Bytes adds a key (variable name) and slice of bytes to the logging event in hex.
func (*Event) Caller ¶
Caller writes the line number and file of the source code that the current function was called from, as the @c_line and @c_file keys.
func (*Event) Line ¶
Line writes the current line number and file of the source code as the @line and @file keys.
func (*Event) Msg ¶
Msg writes the accumulated log entry to the log, along with the message provided.
func (*Event) Msgf ¶
Msgf writes a message formatted as per fmt.Sprintf. It's likely to be slower than any other log event method.
type Logger ¶
type Logger struct {
ErrorWriter io.Writer
InfoWriter io.Writer
DebugWriter io.Writer
Timestamp string
UTC bool
ErrorTag []byte
WarnTag []byte
InfoTag []byte
DebugTag []byte
KeyStart []byte
KeyEnd []byte
Closer func()
}
func NewCloudLogger ¶ added in v1.0.3
func NewCloudLogger() *Logger
NewCloudLogger creates a new logger with output to stdout and stderr, no ANSI codes or timestamps.
func NewConsoleLogger ¶
func NewConsoleLogger() *Logger
NewConsoleLogger creates a new logger with output to stdout and stderr, ANSI colored logging level tags, and timestamps to 1 second precision.
func NewFileLogger ¶
NewFileLogger creates a new logger with output to the error and info log filenames provided, no ANSI codes, and timestamps to 1 second precision.
func NewLogger ¶ added in v1.0.3
func NewLogger() *Logger
NewLogger attempts to determine whether stdout is connected to the console. If so, it returns a ConsoleLogger; if not, it returns a PipeLogger.
func NewPipeLogger ¶ added in v1.0.3
func NewPipeLogger() *Logger
NewPipeLogger creates a new logger with output to stdout and stderr, no ANSI codes, and timestamps to 1 second precision.
func (*Logger) Error ¶
Error returns an error level logging event you can add values and messages to
Source Files
Directories