spruce

README

Spruce

Spruce pretty-prints Go structured logs for humans.

Spruce provides an slog.Handler implementation that acts as an adaptor between an slog.Logger and the io.Writer and testing.TB interfaces.

It is intended for use in places where structured log messages will be read by humans, such as within tests or during development. The output format is not particular suitable for machine parsing; use the built-in JSON or text formatters for that.

Example Usage

package pkg_test

import (
    "log/slog"
    "testing"

    "github.com/dogmatiq/spruce"
)

func TestSomething(t *testing.T) {
    // Create a new spruce logger that directs logs to t.
    logger := spruce.NewTestLogger(t)

    // Run the application code that is being tested, and direct its log output
    // to the test log.
    systemUnderTest(logger)
}

// systemUnderTest is your existing application code that uses an [slog.Logger].
func systemUnderTest(logger *slog.Logger) {
    // Log a message with some complex structured attributes.
    logger.Info(
		"hello, world!",
		slog.Group(
			"<group b>",
			"<key-1>", "<value-1>",
			"<key-2>", "<value-2>",
		),
		slog.Group(
			"<group a>",
			"<key-1>", "<value-1>",
		),
	)
}

The above test produces the following output:

spruce.go:76: [INFO] hello, world!
    ├─┬ <group b>
    │ ├── <key-1> ┈ <value-1>
    │ ╰── <key-2> ┈ <value-2>
    ╰─┬ <group a>
      ╰── <key-1> ┈ <value-1>

Documentation

Overview

Package spruce providers an slog.Handler that writes pretty-printed structured logs to a testing.T (or compatible) logger.

Index

• func NewStreamHandler(w io.Writer) slog.Handler
• func NewStreamLogger(w io.Writer) *slog.Logger
• func NewTestHandler(t TestingT) slog.Handler
• func NewTestLogger(t TestingT) *slog.Logger
• type TestingT

Functions

func NewStreamHandler

func NewStreamHandler(w io.Writer) slog.Handler

NewStreamHandler returns a new slog.Handler that writes to w.

func NewStreamLogger

func NewStreamLogger(w io.Writer) *slog.Logger

NewStreamLogger returns a slog.Logger that writes to w.

func NewTestHandler

func NewTestHandler(t TestingT) slog.Handler

NewTestHandler returns a new slog.Handler that writes to t.

func NewTestLogger

func NewTestLogger(t TestingT) *slog.Logger

NewTestLogger returns a slog.Logger that writes to t.

Types

type TestingT

type TestingT interface {
	Log(...any)
}

TestingT is the subset of testing.TB that is used to write logs.