devlog

Go library that provides utilities for structured logging, building on the standard log/slog package. It provides two independent packages:

• devlog implements a slog.Handler with a human-readable output format, designed for local development and CLI tools
• devlog/log is a thin wrapper over the logging API of log/slog, providing:
  • Utility functions for log message formatting (log.Infof, log.Errorf, etc.)
  • Error-aware logging functions, which structure errors to be formatted consistently as log attributes
  • log.AddContextAttrs, a function for adding log attributes to a context.Context, applying the attributes to all logs made in that context

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

Docs:pkg.go.dev/hermannm.dev/devlog

Contents:

• Usage
  • Using the devlog output handler
  • Using the devlog/log logging API
• Maintainer's guide
• Credits

Usage

Using the devlog output handler

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

import (
"log/slog""hermannm.dev/devlog"
)
funcmain() {
logHandler:=devlog.NewHandler(os.Stdout, nil)
slog.SetDefault(slog.New(logHandler))
}

Logging with slog will now use this handler. So the following log:

slog.Info("Server started", "port", 8000, "environment", "DEV")

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

Structs, slices and other non-primitive types are encoded as pretty-formatted JSON, so this example:

typeEventstruct {
IDint`json:"id"`Typestring`json:"type"`
}
event:=Event{ID: 1000, Type: "ORDER_UPDATED"}
slog.Error("Failed to process event", "event", event)

...gives this output:

devlog's output is meant to be easily read by a developer working locally. However, you may want a more structured format for production systems, to make log analysis easier. You can get both by conditionally choosing the log handler for your application, like this:

varlogHandler slog.Handlerswitchos.Getenv("ENVIRONMENT") {
case"LOCAL", "TEST":
// Pretty-formatted logs for local development and testslogHandler=devlog.NewHandler(os.Stdout, nil)
default:
// Structured JSON logs for deployed environmentslogHandler=slog.NewJSONHandler(os.Stdout, nil)
}
slog.SetDefault(slog.New(logHandler))

Using the devlog/log logging API

Unlike log/slog, devlog/log provides logging functions that take an error. When an error is passed to such a logging function, it is attached to the log as a cause attribute, so errors are structured consistently between logs.

import (
"context""errors""hermannm.dev/devlog/log"
)
funcexample(ctx context.Context) {
err:=errors.New("database insert failed")
log.Error(ctx, err, "Failed to store event")
}

This gives the following output (using the devlog output handler):

The package also provides log.AddContextAttrs, a function for adding log attributes to a context.Context. These attributes are added to all logs where the context is passed, so this example:

funcprocessEvent(ctx context.Context, eventEvent) {
ctx=log.AddContextAttrs(ctx, "eventId", event.ID)
log.Debug(ctx, "Started processing event")
// ...log.Debug(ctx, "Finished processing event")
}

...gives this output:

This can help you trace connected logs in your system (especially when using a more structured JSON output in production, allowing you to filter on all logs with a specific eventId).

In order to encourage propagating context attributes, all log functions in this package take a context.Context. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Maintainer's guide

Publishing a new release

• Run tests and linter (golangci-lint):

  go test ./... && golangci-lint run
  

• Add an entry to CHANGELOG.md (with the current date)
  • Remember to update the link section, and bump the version for the [Unreleased] link
• Create commit and tag for the release (update TAG variable in below command):

  TAG=vX.Y.Z && git commit -m "Release ${TAG}" && git tag -a "${TAG}" -m "Release ${TAG}" && git log --oneline -2
  

• Push the commit and tag:

  git push && git push --tags
  

  • Our release workflow will then create a GitHub release with the pushed tag's changelog entry

Credits

• Jonathan Amsterdam for his fantastic Guide to Writing slog Handlers