shandler

README

SLOG Handler with more knobs

As great as log/slog is, the provided handlers don't have enough customization knobs. This tries to provide more flexibility to the user.

Installation

go get disorder.dev/shandler

Features

WithJSON

Enables JSON output for the log message. This is useful for structured logging.

WithLogLevel

Controls the log level for the message. This is useful for filtering messages.

WithTimeFormat

Controls the time format for the messages.

WithTextOutputFormat

This is a format string that gets used in text based logs. It takes 3 strings: time, level, and message (in that order). Include a newline at the end of your string.

WithStdOut

Controls which io.Writer is used for non-error log messages.

WithStdErr

Controls which io.Writer is used for error messages.

WithColor

Adds color to the log levels in text mode

With{Debug|Info|Warn|Error}Color

Overrides the default color for the log level.

WithShortLevels

Prints 3 character log levels instead of the full name. In text mode, this helps keep the log lines visually straight.

Examples

logger = slog.New(shandler.NewHandler(
	shandler.WithLogLevel(slog.LevelDebug),
	shandler.WithTimeFormat(time.RFC822),
	shandler.WithTextOutputFormat("%s | %s | %s\n"),
	shandler.WithStdErr(os.Stdout),
))
logger.With(slog.String("app", "myapp")).Debug("test")

Trace Log Level

Library includes an easier way to log trace messages. This is useful for debugging chatty logs.

logger = slog.New(shandler.NewHandler(
	shandler.WithLogLevel(shandler.LevelTrace),
))
logger.Log(context.Background(), shandler.LevelTrace, "trace test")

Benchmarks if you're into that sort of thing

goos: linux
goarch: amd64
pkg: disorder.dev/shandler
cpu: 13th Gen Intel(R) Core(TM) i9-13900H

BenchmarkHandlers/handler_text_log-20            3211198               351.4 ns/op
BenchmarkHandlers/stdlib_text_log-20             3325005               356.1 ns/op
BenchmarkHandlers/handler_json_log-20            2108128               592.3 ns/op
BenchmarkHandlers/stdlib_json_log-20             3445792               379.6 ns/op

PASS
ok      disorder.dev/shandler   6.604s

The JSON Handler here is much slower as it uses the JSON library under the covers. The stdlib implementation builds the string manually, so its faster. 🤷🏼‍♀️

Documentation

Index

• Constants
• func ToConfig(h slog.Handler) ([]byte, error)
• type Handler
  • func NewHandler(opts ...HandlerOption) *Handler
  • func NewHandlerFromConfig(config []byte, stdout, stderr []io.Writer) (*Handler, error)
  • func (n *Handler) Enabled(_ context.Context, level slog.Level) bool
  • func (n *Handler) Handle(ctx context.Context, record slog.Record) error
  • func (n Handler) MarshalJSON() ([]byte, error)
  • func (n *Handler) UnmarshalJSON(data []byte) error
  • func (n *Handler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (n *Handler) WithGroup(name string) slog.Handler
• type HandlerOption
  • func WithColor() HandlerOption
  • func WithDebugColor(color string) HandlerOption
  • func WithErrorColor(color string) HandlerOption
  • func WithFatalColor(color string) HandlerOption
  • func WithGroupFilter(filter []string) HandlerOption
  • func WithGroupTextOutputFormat(format string) HandlerOption
  • func WithInfoColor(color string) HandlerOption
  • func WithJSON() HandlerOption
  • func WithLogLevel(level slog.Level) HandlerOption
  • func WithShortLevels() HandlerOption
  • func WithStdErr(err ...io.Writer) HandlerOption
  • func WithStdOut(out ...io.Writer) HandlerOption
  • func WithTextOutputFormat(format string) HandlerOption
  • func WithTimeFormat(format string) HandlerOption
  • func WithTraceColor(color string) HandlerOption
  • func WithWarnColor(color string) HandlerOption

Constants

const (
	LevelTrace slog.Level = slog.LevelDebug - 2
	LevelFatal slog.Level = slog.LevelError + 2
)

Functions

func ToConfig

func ToConfig(h slog.Handler) ([]byte, error)

Types

type Handler

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

func NewHandler

func NewHandler(opts ...HandlerOption) *Handler

func NewHandlerFromConfig

func NewHandlerFromConfig(config []byte, stdout, stderr []io.Writer) (*Handler, error)

NewHandlerFromConfig will allow you to pass in the settings to slog.New(NewHandlerFromConfig). You will need to inclused the io.Writers in the NewHandlerFromConfig call as they are not serializable. Use ToConfig to get the config of your original Handler

func (*Handler) Enabled

func (n *Handler) Enabled(_ context.Context, level slog.Level) bool

func (*Handler) Handle

func (n *Handler) Handle(ctx context.Context, record slog.Record) error

func (Handler) MarshalJSON

func (n Handler) MarshalJSON() ([]byte, error)

func (*Handler) UnmarshalJSON

func (n *Handler) UnmarshalJSON(data []byte) error

func (*Handler) WithAttrs

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

func (*Handler) WithGroup

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

type HandlerOption

type HandlerOption func(*Handler)

func WithColor

func WithColor() HandlerOption

func WithDebugColor

func WithDebugColor(color string) HandlerOption

func WithErrorColor

func WithErrorColor(color string) HandlerOption

func WithFatalColor

func WithFatalColor(color string) HandlerOption

func WithGroupFilter

func WithGroupFilter(filter []string) HandlerOption

You can use this to filter out logs from specific groups

func WithGroupTextOutputFormat

func WithGroupTextOutputFormat(format string) HandlerOption

func WithInfoColor

func WithInfoColor(color string) HandlerOption

func WithJSON

func WithJSON() HandlerOption

func WithLogLevel

func WithLogLevel(level slog.Level) HandlerOption

func WithShortLevels

func WithShortLevels() HandlerOption

func WithStdErr

func WithStdErr(err ...io.Writer) HandlerOption

func WithStdOut

func WithStdOut(out ...io.Writer) HandlerOption

func WithTextOutputFormat

func WithTextOutputFormat(format string) HandlerOption

WithTextOutputFormat sets the format for the group output. The order of the fields are: 1. Record Level (Debug, Info, Warn, Error) 2. Record Time 3. Record Message

The default format is "[%s] %s - %s\n". If you want to rearrange the fields, you can use the indexes: "%[3]s %[1]s %[2]\n" This will output "{Record Message} {Record Level} {Record Time}\n"

User must provide newline in format

func WithTimeFormat

func WithTimeFormat(format string) HandlerOption

func WithTraceColor

func WithTraceColor(color string) HandlerOption

func WithWarnColor

func WithWarnColor(color string) HandlerOption