slog

README

slog - structured logging for lazy gophers

Overview

Slog parses and converts log messages produced by the standard logger to JSON objects. Any key=value text fragments found in the message are extracted as separate JSON fields. No boilerplate, just Printf.

Install

go get -u github.com/askeladdk/slog

Quickstart

Use the function slog.New to create a log.Logger that produces structured logs. It has the same signature as log.New in the standard library and is backwards compatible.

Enable all features and create a logger:

logger := slog.New(os.StdErr, "level=info ", slog.LstdFlags)

Log an event:

logger.Printf("requested url=%s with method=%s with response status=%d", "/index.html", "GET", 200)

Result:

{"time":"2021-08-08T19:06:35.252044Z","mesg":"level=info requested url=/index.html with method=GET with response status=200","level":"info","url":"/index.html","method":"GET","status":200}

Use slog.NewWriter to create a new structured writer and attach it to the default logger with SetOutput:

log.SetFlags(slog.LstdFlags)
log.SetOutput(slog.NewWriter(os.StdErr, log.Default()))
log.Println("hello world")

Note that the logger flags and prefix must not be changed after a writer has been created.

Read the rest of the documentation on pkg.go.dev. It's easy-peasy!

Performance

Unscientific benchmarks on my laptop suggest that slog is about twice as memory and thrice as CPU intensive as the standard logger by itself.

% go test -bench=. -benchmem -benchtime=1000000x
goos: darwin
goarch: amd64
pkg: github.com/askeladdk/slog
cpu: Intel(R) Core(TM) i5-5287U CPU @ 2.90GHz
BenchmarkStdLogger-4          	 1000000	      1555 ns/op	     544 B/op	       3 allocs/op
BenchmarkSlog-4              	 1000000	      3251 ns/op	     860 B/op	       5 allocs/op
BenchmarkSlogParseFields-4   	 1000000	      4556 ns/op	     860 B/op	       5 allocs/op

License

Package slog is released under the terms of the ISC license.

Documentation

Overview

Package slog implements structured logging for lazy gophers.

Like the standard logger, slog is configured via flags. It uses all the standard flags and introduces two new ones, Lcolor and Lparsefields.

Flag Lcolor colorizes the output if the output writer is detected to be a tty.

Flag Lparsefields parses the log message (including prefix if log.Lmsgprefix is set) for key-value pairs and stores them as separate fields in the JSON object. A key-value pair is any fragment of text of the form key=value or key="another value". The key cannot contain spaces and the equals sign cannot be surrounded by spaces. The value can only contain spaces if it is quoted. Slog does not check for duplicate field names.

The standard logger produces non-standard timestamps. Slog converts the timestamps to RFC3339 format if the flags log.Ldate, log.Ltime and log.LUTC are all set and stores it in the time field.

The prefix, if any, is parsed differently depending on whether log.Lmsgprefix is set. If it is not, then the prefix is trimmed of spaces and punctuation marks and stored in the prfx field. If it is, then it is considered part of the log message. The log message is stored in the mesg field.

If flags log.Llongfile or log.Lshortfile are set, slog parses the file name and line number in two separate fields named fnam and flno.

Index

• Constants
• func New(w io.Writer, prefix string, flag int) *log.Logger
• func NewWriter(w io.Writer, l *log.Logger) io.Writer

Constants

const (
	// Lcolor enables colorized output to the terminal.
	Lcolor = 1 << (iota + 16)
	// Lparsefields enables parsing the message for key-value fields.
	Lparsefields
	// LstdFlags defines an initial set of flags.
	LstdFlags = log.LstdFlags | log.Lmicroseconds | log.LUTC | log.Lmsgprefix | Lcolor | Lparsefields
)

Functions

func New

func New(w io.Writer, prefix string, flag int) *log.Logger

New creates a new log.Logger that produces structured logs. The prefix and flags of the logger must not be changed afterwards.

func NewWriter

func NewWriter(w io.Writer, l *log.Logger) io.Writer

NewWriter creates a new structured logging output writer. The prefix and flags of the logger must not be changed afterwards.