logging

Documentation

Overview

Package logging provides a context-scoped logger built on the standard library's log/slog.

A logger is carried on a context.Context with WithLogger and retrieved with FromContext. When no logger is present on the context, FromContext returns the process DefaultLogger so callers never have to nil-check.

Middleware in this framework stores a request logger on the context, so handlers can simply call logging.FromContext(r.Context()).

Index

• func DefaultLogger() *slog.Logger
• func FromContext(ctx context.Context) *slog.Logger
• func LevelFromString(s string) slog.Level
• func Named(l *slog.Logger, name string) *slog.Logger
• func NewLogger(level slog.Level, development bool) *slog.Logger
• func NewLoggerFromConfig(c Config) *slog.Logger
• func NewLoggerFromEnv() *slog.Logger
• func TestLogger(tb testing.TB) *slog.Logger
• func WithLogger(ctx context.Context, logger *slog.Logger) context.Context
• type Config

Examples

• FromContext

Functions

func DefaultLogger

func DefaultLogger() *slog.Logger

DefaultLogger returns the process-wide default logger, constructing it from the environment on first use via NewLoggerFromEnv.

func FromContext

func FromContext(ctx context.Context) *slog.Logger

FromContext returns the logger stored on ctx by WithLogger. If no logger is present, it returns DefaultLogger.

Example

package main

import (
	"context"

	"github.com/mikehelmick/go-bananas/logging"
)

func main() {
	// Store a logger on a context (typically done once per request by
	// middleware), then retrieve it deeper in the call stack.
	ctx := logging.WithLogger(context.Background(), logging.DefaultLogger())

	logger := logging.FromContext(ctx)
	logger.Info("handling request", "path", "/")

	// Components identify themselves with a named logger.
	logging.Named(logger, "middleware.CSRF").Debug("validated token")
}

func LevelFromString

func LevelFromString(s string) slog.Level

LevelFromString converts a case-insensitive level string ("debug", "info", "warn"/"warning", "error") to an slog.Level. Unrecognized or empty values map to slog.LevelInfo.

func Named

func Named(l *slog.Logger, name string) *slog.Logger

Named returns a logger that tags every record with a "logger" attribute set to name. It is the slog equivalent of a named/sub logger and is typically used to identify the component emitting a log line, e.g. Named(l, "middleware.CSRF").

func NewLogger

func NewLogger(level slog.Level, development bool) *slog.Logger

NewLogger creates a new logger at the given level. When development is true the logger writes human-readable text to standard error; otherwise it writes structured JSON to standard error.

func NewLoggerFromConfig

func NewLoggerFromConfig(c Config) *slog.Logger

NewLoggerFromConfig builds a *slog.Logger from c. The Level is resolved via LevelFromString and a Mode of "development" (case-insensitive, trimmed) selects the text handler; any other Mode selects the JSON handler.

func NewLoggerFromEnv

func NewLoggerFromEnv() *slog.Logger

NewLoggerFromEnv creates a new logger from the environment. It reads LOG_LEVEL (debug, info, warn, or error; defaulting to info) to determine the level and LOG_MODE (development for text output; defaulting to production/JSON) to determine the output format. Environment parsing is delegated to Config and NewLoggerFromConfig.

func TestLogger

func TestLogger(tb testing.TB) *slog.Logger

TestLogger returns a logger that writes debug-level text output through the provided testing.TB, so log lines are attributed to the running test and hidden unless the test fails or runs with -v.

func WithLogger

func WithLogger(ctx context.Context, logger *slog.Logger) context.Context

WithLogger returns a copy of ctx that carries the provided logger. Retrieve it with FromContext.

Types

type Config

type Config struct {
	// Level is the minimum log level ("debug", "info", "warn"/"warning", or
	// "error"). Unrecognized values fall back to info (see [LevelFromString]).
	Level string `env:"LOG_LEVEL, default=info"`

	// Mode selects the output format. "development" produces human-readable text
	// output; any other value (including the "production" default) produces
	// structured JSON.
	Mode string `env:"LOG_MODE, default=production"`
}

Config controls logger construction from the environment. The struct tags are compatible with github.com/sethvargo/go-envconfig.