yadu

README

yadu - a human readable yaml based slog.Handler

Introduction

Package yadu provides a handler for the log/slog logging framework.

It generates a mixture of text lines containing the timestamp and log message and a YAML dump of the provided attibutes.

Log format

The log format generated by yadu looks like this:

2023-04-02T10:50.09 EDT LEVEL Message text
    foo: value
    bar: 12345

Example

logger := slog.New(yadu.NewHandler(os.Stdout, nil))

type body string

type Ammo struct {
        Forweapon string
        Impact    int
        Cost      int
        Range     int
}

type Enemy struct {
    Alive  bool
    Health int
    Name   string
    Body   body `yaml:"-"` // not printed
    Ammo   []Ammo
}

e := &Enemy{Alive: true, Health: 10, Name: "Bodo", Body: "body\nbody\n",
    Ammo: []Ammo{{Forweapon: "Railgun", Range: 400, Impact: 100, Cost: 100000}},
}

slog.Info("info", "enemy", e, "spawn", 199)

Output:

2024-01-18T02:57.41 CET INFO: info 
    enemy:
        alive: true
        health: 10
        name: Bodo
        ammo:
            - forweapon: Railgun
              impact: 100
              cost: 100000
              range: 400
    spawn: 199

See example/example.go for usage.

Installation

Execute this to add the module to your project:

go get github.com/tlinden/yadu

Configuration

You can tweak the behavior of the handler as any other handler by using the Options struct:

func removeTime(_ []string, a slog.Attr) slog.Attr {
        if a.Key == slog.TimeKey {
                return slog.Attr{}
        }
        return a
}

opts := &yadu.Options{
           Level: slog.LevelDebug,
           ReplaceAttr: removeTime,
        }

Pass this object to yadu.NewHandler().

Because you can pass whole structs to the logger which will be dumped using YAML, there's also a way to exclude fields from being printed:

type User struct {
  Id int
  User string
  Pass string `yaml:"-"`
}

If you're already using YAML tags for other purposes you can also just add a LogValue() method to your struct, which will be called by slog. Refer to the slog documentation how to use it.

You can also modify the time format using yadu.Options.TimeFormat.

Acknowledgements

I wrote most of the code with the help of the humane slog handler. Also helpfull was the guide to writing slog handlers.

• humane slog handler
• A Guide to Writing slog Handlers
• A Comprehensive Guide to Structured Logging in Go

LICENSE

This module is published under the terms of the BSD 3-Clause License. Please read the file LICENSE for details.

Author

Thomas von Dein <git |AT| daemon.de>

Documentation

Index

• Constants
• type Handler
  • func NewHandler(out io.Writer, opts *Options) *Handler
  • func (h *Handler) Enabled(_ context.Context, l slog.Level) bool
  • func (h *Handler) Handle(ctx context.Context, r slog.Record) error
  • func (h *Handler) Postprocess(yamlstr []byte) string
  • func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *Handler) WithGroup(name string) slog.Handler
• type Options

Constants

const DefaultTimeFormat = "2006-01-02T03:04.05 MST"

We use RFC datestring by default

const VERSION = "0.1.3"

Types

type Handler

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

func NewHandler

func NewHandler(out io.Writer, opts *Options) *Handler

NewHandler returns a log/slog.Handler using the receiver's options. Default options are used if opts is nil.

func (*Handler) Enabled

func (h *Handler) Enabled(_ context.Context, l slog.Level) bool

Enabled indicates whether the receiver logs at the given level.

func (*Handler) Handle

func (h *Handler) Handle(ctx context.Context, r slog.Record) error

func (*Handler) Postprocess

func (h *Handler) Postprocess(yamlstr []byte) string

func (*Handler) WithAttrs

func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler

sub logger is to be created, possibly with attrs, add them to h.attrs

func (*Handler) WithGroup

func (h *Handler) WithGroup(name string) slog.Handler

WithGroup returns a new log/slog.Handler with name appended to the receiver's groups.

type Options

type Options struct {
	Level       slog.Leveler
	ReplaceAttr func(groups []string, a slog.Attr) slog.Attr
	TimeFormat  string
	AddSource   bool
	NoColor     bool
}

Options are options for the Yadu log/slog.Handler.

Level sets the minimum log level.

ReplaceAttr is a function you can define to customize how supplied attrs are being handled. It is empty by default, so nothing will be altered.

Loglevel and message cannot be altered using ReplaceAttr. Timestamp can only be removed, see example. Keep in mind that everything will be passed to yaml.Marshal() in the end.