slog

README

slog

slog is a minimal structured logging library for Go.

Install

go get cdr.dev/slog

Features

• Minimal API
• First class context.Context support
• First class testing.TB support
  • Package slogtest/assert provides test assertion helpers
• Beautiful human readable logging output
  • Prints multiline fields and errors nicely
• Machine readable JSON output
• GCP Stackdriver support
• Stdlib log adapter
• Skip caller frames with slog.Helper
• Encodes values as if with json.Marshal
• Transparently log opencensus trace and span IDs
• Single dependency on go.opencensus.io
• Log to multiple sinks

Example

Many more examples available at godoc.

log := slog.Make(sloghuman.Sink(os.Stdout))

log.Info(context.Background(), "my message here",
    slog.F("field_name", "something or the other"),
    slog.F("some_map", slog.M(
        slog.F("nested_fields", time.Date(2000, time.February, 5, 4, 4, 4, 0, time.UTC)),
    )),
    slog.Error(
        xerrors.Errorf("wrap1: %w",
            xerrors.Errorf("wrap2: %w",
                io.EOF,
            ),
        ),
    ),
)

Why?

At Coder we’ve used Uber’s zap for several years. It is a fantastic library for performance. Thanks Uber!

However we felt the API and developer experience could be improved.

Here is a list of reasons how we improved on zap with slog.

1. slog has a minimal API surface

   • Compare slog to zap and zapcore.
   • The sprawling API makes zap hard to understand, use and extend.

2. slog has a concise semi typed API

   • We found zap's fully typed API cumbersome. It does offer a sugared API but it's too easy to pass an invalid fields list since there is no static type checking. Furthermore, it's harder to read as there is no syntax grouping for each key value pair.
   • We wanted an API that only accepted the equivalent of zap.Any for every field. This is slog.F.

3. sloghuman uses a very human readable format

   • It colors distinct parts of each line to make it easier to scan logs. Even the JSON that represents the fields in each log is syntax highlighted so that is very easy to scan. See the screenshot above.
     • zap lacks appropriate colors for different levels and fields.
   • slog automatically prints one multiline field after the log to make errors and such much easier to read.
     • zap logs multiline fields and errors stack traces as JSON strings which made them unreadable in a terminal.
   • When logging to JSON, slog automatically converts a golang.org/x/xerrors chain into an array with fields for the location and wrapping messages.

4. Full context.Context support

   • slog lets you set fields in a context.Context such that any log with the context prints those fields.
   • We wanted to be able to pull up all relevant logs for a given trace, user or request. With zap, we were plugging these fields in for every relevant log or passing around a logger with the fields set. This became very verbose.

5. Simple and easy to extend

   • A new backend only has to implement the simple Sink interface.
   • The Logger type provides a nice API around Sink but also implements Sink to allow for composition.
   • zap is hard and confusing to extend. There are too many structures and configuration options.

6. Structured logging of Go structures with json.Marshal

   • Entire encoding process is documented on godoc.
   • With zap, We found ourselves often implementing zap's ObjectMarshaler to log Go structures. This was verbose and most of the time we ended up only implementing fmt.Stringer and using zap.Stringer instead.

7. slog takes inspiration from Go's stdlib and implements slog.Helper which works just like t.Helper

   • It marks the calling function as a helper and skips it when reporting location info.
   • We had many helper functions for logging but we wanted the line reported to be of the parent function. zap has an API for this but it's verbose and requires passing the logger around explicitly.

8. Tight integration with stdlib's testing package

   • You can configure slogtest to exit on any ERROR logs and it has a global stateless API that takes a testing.TB so you do not need to create a logger first.
   • Test assertion helpers are provided in slogtest/assert.
   • zap has zaptest but the API surface is large and doesn't integrate well. It does not support any of the features described above.

Documentation

Overview

Package slog implements minimal structured logging.

See https://cdr.dev/slog for overview docs and a comparison with existing libraries.

The examples are the best way to understand how to use this library effectively.

The Logger type implements a high level API around the Sink interface. Logger implements Sink as well to allow composition.

Implementations of the Sink interface are available in the sloggers subdirectory.

Example

package main

import (
	"context"
	"io"
	"os"
	"time"

	"golang.org/x/xerrors"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
)

func main() {
	log := slog.Make(sloghuman.Sink(os.Stdout))

	log.Info(context.Background(), "my message here",
		slog.F("field_name", "something or the other"),
		slog.F("some_map", slog.M(
			slog.F("nested_fields", time.Date(2000, time.February, 5, 4, 4, 4, 0, time.UTC)),
		)),
		slog.Error(
			xerrors.Errorf("wrap1: %w",
				xerrors.Errorf("wrap2: %w",
					io.EOF,
				),
			),
		),
	)

	// 2019-12-09 05:04:53.398 [INFO]	<example.go:16>	my message here	{"field_name": "something or the other", "some_map": {"nested_fields": "2000-02-05T04:04:04Z"}} ...
	//  "error": wrap1:
	//      main.main
	//          /Users/nhooyr/src/cdr/scratch/example.go:22
	//    - wrap2:
	//      main.main
	//          /Users/nhooyr/src/cdr/scratch/example.go:23
	//    - EOF
}

Example (Marshaller)

package main

import (
	"context"
	"os"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
)

type myStruct struct {
	foo int
	bar int
}

func (s myStruct) MarshalJSON() ([]byte, error) {
	return slog.M(
		slog.F("foo", s.foo),
		slog.F("bar", s.foo),
	).MarshalJSON()
}

func main() {
	l := slog.Make(sloghuman.Sink(os.Stdout))

	l.Info(context.Background(), "wow",
		slog.F("myStruct", myStruct{
			foo: 1,
			bar: 2,
		}),
	)

	// 2019-12-16 17:31:37.120 [INFO]	<example_marshaller_test.go:26>	wow	{"myStruct": {"foo": 1, "bar": 1}}
}

Example (Multiple)

package main

import (
	"context"
	"os"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
	"cdr.dev/slog/sloggers/slogstackdriver"
)

func main() {
	l := slog.Make(sloghuman.Sink(os.Stdout))

	f, err := os.OpenFile("stackdriver", os.O_WRONLY|os.O_APPEND|os.O_CREATE, 0o644)
	if err != nil {
		l.Fatal(context.Background(), "failed to open stackdriver log file", slog.Error(err))
	}

	l = l.AppendSinks(slogstackdriver.Sink(f))

	l.Info(context.Background(), "log to stdout and stackdriver")

	// 2019-12-07 20:59:55.790 [INFO]	log to stdout and stackdriver
}

Example (Struct)

package main

import (
	"context"
	"os"
	"time"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
)

func main() {
	l := slog.Make(sloghuman.Sink(os.Stdout))

	type hello struct {
		Meow int       `json:"meow"`
		Bar  string    `json:"bar"`
		M    time.Time `json:"m"`
	}

	l.Info(context.Background(), "check out my structure",
		slog.F("hello", hello{
			Meow: 1,
			Bar:  "barbar",
			M:    time.Date(2000, time.February, 5, 4, 4, 4, 0, time.UTC),
		}),
	)

	// 2019-12-16 17:31:51.769 [INFO]	<example_test.go:56>	check out my structure	{"hello": {"meow": 1, "bar": "barbar", "m": "2000-02-05T04:04:04Z"}}
}

Example (Testing)

package main

import (
	"testing"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/slogtest"
)

func main() {
	// Provided by the testing package in tests.
	var t testing.TB

	slogtest.Info(t, "my message here",
		slog.F("field_name", "something or the other"),
	)

	// t.go:55: 2019-12-05 21:20:31.218 [INFO]	my message here	field_name="something or the other"
}

Index

• func Helper()
• func Stdlib(ctx context.Context, l Logger, level Level) *log.Logger
• func With(ctx context.Context, fields ...Field) context.Context
• type Field
  • func Error(err error) Field
  • func F(name string, value interface{}) Field
• type Level
  • func (l Level) String() string
• type Logger
  • func Make(sinks ...Sink) Logger
  • func (l Logger) AppendSinks(s ...Sink) Logger
  • func (l Logger) Critical(ctx context.Context, msg string, fields ...any)
  • func (l Logger) Debug(ctx context.Context, msg string, fields ...any)
  • func (l Logger) Error(ctx context.Context, msg string, fields ...any)
  • func (l Logger) Fatal(ctx context.Context, msg string, fields ...any)
  • func (l Logger) Info(ctx context.Context, msg string, fields ...any)
  • func (l Logger) Leveled(level Level) Logger
  • func (l Logger) Log(ctx context.Context, e SinkEntry)
  • func (l Logger) Named(name string) Logger
  • func (l Logger) Sync()
  • func (l Logger) Warn(ctx context.Context, msg string, fields ...any)
  • func (l Logger) With(fields ...Field) Logger
• type Map
  • func M(fs ...Field) Map
  • func (m Map) MarshalJSON() ([]byte, error)
• type Sink
• type SinkEntry

Examples

• Package
• Package (Marshaller)
• Package (Multiple)
• Package (Struct)
• Package (Testing)
• Helper
• Logger.Leveled
• Logger.Named
• Stdlib
• With

Functions

func Helper

func Helper()

Helper marks the calling function as a helper and skips it for source location information. It's the slog equivalent of testing.TB.Helper().

Example

package main

import (
	"context"
	"net/http"
	"os"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
)

func httpLogHelper(ctx context.Context, status int) {
	slog.Helper()

	l.Info(ctx, "sending HTTP response",
		slog.F("status", status),
	)
}

var l = slog.Make(sloghuman.Sink(os.Stdout))

func main() {
	ctx := context.Background()
	httpLogHelper(ctx, http.StatusBadGateway)

	// 2019-12-07 21:18:42.567 [INFO]	<example_helper_test.go:24>	sending HTTP response	{"status": 502}
}

func Stdlib

func Stdlib(ctx context.Context, l Logger, level Level) *log.Logger

Stdlib creates a standard library logger from the given logger.

All logs will be logged at the level set by the logger and the given ctx will be passed to the logger's Log method, thereby logging all fields and tracing info in the context.

You can redirect the stdlib default logger with log.SetOutput to the Writer on the logger returned by this function. See the example.

Example

package main

import (
	"context"
	"os"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
)

func main() {
	ctx := slog.With(context.Background(), slog.F("field", 1))
	l := slog.Stdlib(ctx, slog.Make(sloghuman.Sink(os.Stdout)), slog.LevelInfo)

	l.Print("msg")

	// 2019-12-07 20:54:23.986 [INFO]	(stdlib)	msg	field=1
}

func With

func With(ctx context.Context, fields ...Field) context.Context

With returns a context that contains the given fields.

Any logs written with the provided context will have the given logs prepended.

It will append to any fields already in ctx.

Example

package main

import (
	"context"
	"os"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
)

func main() {
	ctx := slog.With(context.Background(), slog.F("field", 1))

	l := slog.Make(sloghuman.Sink(os.Stdout))
	l.Info(ctx, "msg")

	// 2019-12-07 20:54:23.986 [INFO]	msg	field=1}
}

Types

type Field

type Field struct {
	Name  string
	Value interface{}
}

Field represents a log field.

func Error

func Error(err error) Field

Error is the standard key used for logging a Go error value.

func F

func F(name string, value interface{}) Field

F is a convenience constructor for Field.

type Level

type Level int

Level represents a log level.

const (
	// LevelDebug is used for development and debugging messages.
	LevelDebug Level = iota

	// LevelInfo is used for normal informational messages.
	LevelInfo

	// LevelWarn is used when something has possibly gone wrong.
	LevelWarn

	// LevelError is used when something has certainly gone wrong.
	LevelError

	// LevelCritical is used when when something has gone wrong and should
	// be immediately investigated.
	LevelCritical

	// LevelFatal is used when the process is about to exit due to an error.
	LevelFatal
)

The supported log levels.

The default level is Info.

func (Level) String

func (l Level) String() string

String implements fmt.Stringer.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger wraps Sink with a nice API to log entries.

Logger is safe for concurrent use.

func Make

func Make(sinks ...Sink) Logger

Make creates a logger that writes logs to the passed sinks at LevelInfo.

func (Logger) AppendSinks

func (l Logger) AppendSinks(s ...Sink) Logger

AppendSinks appends the sinks to the set sink targets on the logger.

func (Logger) Critical

func (l Logger) Critical(ctx context.Context, msg string, fields ...any)

Critical logs the msg and fields at LevelCritical. See Info() for information on the fields argument.

It will then Sync().

func (Logger) Debug

func (l Logger) Debug(ctx context.Context, msg string, fields ...any)

Debug logs the msg and fields at LevelDebug. See Info for information on the fields argument.

func (Logger) Error

func (l Logger) Error(ctx context.Context, msg string, fields ...any)

Error logs the msg and fields at LevelError. See Info() for information on the fields argument.

It will then Sync().

func (Logger) Fatal

func (l Logger) Fatal(ctx context.Context, msg string, fields ...any)

Fatal logs the msg and fields at LevelFatal. See Info() for information on the fields argument.

It will then Sync() and os.Exit(1).

func (Logger) Info

func (l Logger) Info(ctx context.Context, msg string, fields ...any)

Info logs the msg and fields at LevelInfo. Fields may contain any combination of key value pairs, Field, and Map. For example:

log.Info(ctx, "something happened", "user", "alex", slog.F("age", 20))

is equivalent to:

log.Info(ctx, "something happened", slog.F("user", "alex"), slog.F("age", 20))

is equivalent to:

log.Info(ctx, "something happened", slog.M(
	slog.F("user", "alex"),
	slog.F("age", 20),
))

is equivalent to:

log.Info(ctx, "something happened", "user", "alex", "age", 20)

In general, prefer using key value pairs over Field and Map, as that is how the standard library's slog package works.

func (Logger) Leveled

func (l Logger) Leveled(level Level) Logger

Leveled returns a Logger that only logs entries equal to or above the given level.

Example

package main

import (
	"context"
	"os"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
)

func main() {
	ctx := context.Background()

	l := slog.Make(sloghuman.Sink(os.Stdout))
	l.Debug(ctx, "testing1")
	l.Info(ctx, "received request")

	l = l.Leveled(slog.LevelDebug)

	l.Debug(ctx, "testing2")

	// 2019-12-07 21:26:20.945 [INFO]	received request
	// 2019-12-07 21:26:20.945 [DEBU]	testing2
}

func (Logger) Log

func (l Logger) Log(ctx context.Context, e SinkEntry)

Log logs the given entry with the context to the underlying sinks.

It extends the entry with the set fields and names.

func (Logger) Named

func (l Logger) Named(name string) Logger

Named appends the name to the set names on the logger.

Example

package main

import (
	"context"
	"net"
	"os"

	"cdr.dev/slog"
	"cdr.dev/slog/sloggers/sloghuman"
)

func main() {
	ctx := context.Background()

	l := slog.Make(sloghuman.Sink(os.Stdout))
	l = l.Named("http")
	l.Info(ctx, "received request", slog.F("remote address", net.IPv4(127, 0, 0, 1)))

	// 2019-12-07 21:20:56.974 [INFO]	(http)	received request	remote_address=127.0.0.1}
}

func (Logger) Sync

func (l Logger) Sync()

Sync calls Sync on all the underlying sinks.

func (Logger) Warn

func (l Logger) Warn(ctx context.Context, msg string, fields ...any)

Warn logs the msg and fields at LevelWarn. See Info() for information on the fields argument.

func (Logger) With

func (l Logger) With(fields ...Field) Logger

With returns a Logger that prepends the given fields on every logged entry.

It will append to any fields already in the Logger.

type Map

type Map []Field

Map represents an ordered map of fields.

func M

func M(fs ...Field) Map

M is a convenience constructor for Map

func (Map) MarshalJSON

func (m Map) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

It is guaranteed to return a nil error. Any error marshalling a field will become the field's value.

Every field value is encoded with the following process:

1. json.Marshaller is handled.

2. xerrors.Formatter is handled.

3. structs that have a field with a json tag are encoded with json.Marshal.

4. error and fmt.Stringer is handled.

5. slices and arrays go through the encode function for every element.

6. For values that cannot be encoded with json.Marshal, fmt.Sprintf("%+v") is used.

7. json.Marshal(v) is used for all other values.

type Sink

type Sink interface {
	LogEntry(ctx context.Context, e SinkEntry)
	Sync()
}

Sink is the destination of a Logger.

All sinks must be safe for concurrent use.

type SinkEntry

type SinkEntry struct {
	Time time.Time

	Level   Level
	Message string

	LoggerNames []string

	Func string
	File string
	Line int

	SpanContext trace.SpanContext

	Fields Map
}

SinkEntry represents the structure of a log entry. It is the argument to the sink when logging.