devlog

README

devlog

A structured log handler for Go, with a human-readable output format designed for development builds.

Run go get hermannm.dev/devlog to add it to your project!

Usage

devlog.Handler implements slog.Handler, so it can handle output for slog's logging functions. It can be configured as follows:

logHandler := devlog.NewHandler(os.Stdout, nil)
slog.SetDefault(slog.New(logHandler))

Logging with slog will now use this handler:

slog.Warn("No value found for 'PORT' in env, defaulting to 8000")
slog.Info("Server started", "port", 8000, "environment", "DEV")
slog.Error(
	"Database query failed",
	slog.Group("dbError", "code", 60, "message", "UNKNOWN_TABLE"),
)

...giving the following output (using a gruvbox terminal color scheme):

This output is meant to be easily read by a developer working locally. However, you may want a more structured format for production, such as JSON, to make log analysis easier. You can get both by conditionally choosing the log handler for your application, e.g.:

var logHandler slog.Handler
switch os.Getenv("ENVIRONMENT") {
case "PROD":
	logHandler = slog.NewJSONHandler(os.Stdout, nil)
case "DEV":
	logHandler = devlog.NewHandler(os.Stdout, nil)
}

slog.SetDefault(slog.New(logHandler))

devlog/log

To complement devlog's output handling, the devlog/log subpackage provides input handling. It is a thin wrapper over the slog package, with utility functions for log message formatting.

Example using devlog and devlog/log together:

import (
	"errors"
	"os"

	"hermannm.dev/devlog"
	"hermannm.dev/devlog/log"
)

func main() {
	// Shorthand for calling NewHandler with slog.SetDefault
	devlog.InitDefaultLogHandler(os.Stdout, nil)

	user := map[string]any{"id": 2, "username": "hermannm"}
	err := errors.New("username taken")
	log.ErrorCause(err, "Failed to create user", log.JSON("user", user))
}

This gives the following output:

Credits

• Jonathan Amsterdam for his fantastic Guide to Writing slog Handlers

Documentation

Overview

Package devlog implements a structured log (slog) handler, with a human-readable output format designed for development builds.

A devlog.Handler can be configured as follows:

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

Following calls to log/slog's logging functions will use this handler, giving output on the following format:

slog.Info("Server started", "port", 8000, "environment", "DEV")
// [10:31:09] INFO: Server started
//   port: 8000
//   environment: DEV

Check the README to see the output format with colors.

To complement devlog's output handling, the devlog/log subpackage provides input handling. It is a thin wrapper over the slog package, with utility functions for log message formatting.

Index

• func InitDefaultLogHandler(output io.Writer, options *Options)
• func IsColorTerminal(output io.Writer) bool
• type Handler
  • func NewHandler(output io.Writer, options *Options) *Handler
  • func (handler *Handler) Enabled(_ context.Context, level slog.Level) bool
  • func (handler *Handler) Handle(_ context.Context, record slog.Record) error
  • func (handler *Handler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (handler *Handler) WithGroup(name string) slog.Handler
• type Options
• type TimeFormat

Functions

func InitDefaultLogHandler

func InitDefaultLogHandler(output io.Writer, options *Options)

InitDefaultLogHandler is shorthand for:

• Calling NewHandler with the given arguments
• Setting it as the default log handler with slog.SetDefault

func IsColorTerminal

func IsColorTerminal(output io.Writer) bool

IsColorTerminal checks if the given writer is a terminal with ANSI color support. It respects NO_COLOR, FORCE_COLOR and TERM=dumb environment variables.

Types

type Handler

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

Handler is a slog.Handler that outputs log records in a human-readable format, designed for development builds. See the package-level documentation for more on the output format.

func NewHandler

func NewHandler(output io.Writer, options *Options) *Handler

NewHandler creates a log Handler that writes to output, using the given options. If options is nil, the default options are used.

func (*Handler) Enabled

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

Enabled reports whether the handler is configured to log records at the given level.

func (*Handler) Handle

func (handler *Handler) Handle(_ context.Context, record slog.Record) error

Handle writes the given log record to the handler's output. See the package-level documentation for more on the output format.

func (*Handler) WithAttrs

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

WithAttrs returns a new Handler which adds the given attributes to every log record.

func (*Handler) WithGroup

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

WithGroup returns a new Handler where all future log record attributes are nested under the given group name.

type Options

type Options struct {
	// Level is the minimum log record level that will be logged.
	// If nil, defaults to [slog.LevelInfo].
	Level slog.Leveler

	// AddSource adds a 'source' attribute to every log record, with the file name and line number
	// where the log record was produced.
	// Defaults to false.
	AddSource bool

	// DisableColors removes colors from log output.
	//
	// Colors are enabled by default when the [io.Writer] given to [NewHandler] is a terminal with
	// color support (see [IsColorTerminal]).
	DisableColors bool

	// ForceColors skips checking [IsColorTerminal] for color support, and includes colors in log
	// output regardless. It overrides [Options.DisableColors].
	ForceColors bool

	// TimeFormat controls how time is formatted for each log entry. It defaults to
	// [TimeFormatShort], showing just the time and not the date, but can be set to [TimeFormatFull]
	// to include the date as well.
	TimeFormat TimeFormat
}

Options configure a log Handler.

type TimeFormat

type TimeFormat int8

See [Options.TimeFormat].

const (
	// TimeFormatShort includes just the time, not the date, formatted as: [10:57:30]
	//
	// This is the default time format.
	TimeFormatShort TimeFormat = iota

	// TimeFormatFull includes both date and time, formatted as: [2024-09-29 10:57:30]
	TimeFormatFull
)