README.md

logging

Structured logging for Go on top of uber zap with a small, stable interface.

go get github.com/amarin/logging@v0.2.0

Quick start

package main

import "github.com/amarin/logging"

func main() {
	logging.MustInit(
		logging.WithLevel(logging.LevelDebug),
		logging.WithFormat(logging.FormatJSON),
	)
	defer logging.Sync()

	log := logging.NewLogger()
	log.WithKey("user", 42).Info("logged in")
}

Settings can also be loaded from YAML, see docs/configuration.md.

Features

• zap backend behind a compact Logger interface; optional interfaces (Panicer, Namer, Syncer) extend it without breaking custom implementations.
• Levels trace, debug, info, warn, error, panic, fatal, including a real trace level, plus per-logger levels by name (customLevels).
• Runtime level changes (SetLevel, SetNamedLevel, ResetNamedLevel) and an optional HTTP handler (LevelsHandler, disabled by default).
• Fields from context.Context through extractors, static service fields (fields), typed and redacted keys (TypedKey, RedactedKey, WithValuesFrom).
• Redaction of sensitive fields by key (redact), control-character escaping in the text format.
• Hooks for metrics (WithHook), for example to count errors.
• Output to stdout, stderr, a file (append), syslog (UDP, TCP, unix socket) or your own io.Writer.
• TestLogger that records entries in memory (NewTestLogger, UseTestLogger).
• slog.Handler adapter (NewSlogHandler, NewSlogLogger) on Go 1.21+.
• go.mod stays at go 1.18; code for newer Go versions is enabled by build tags. The logging_legacy tag forces the fallback implementation on any Go version.

Not sure whether this package fits your project? See When to choose which logger.

Documentation

• docs/usage.md: initialization, loggers, fields, context, runtime levels, HTTP handler, hooks, edge cases.
• docs/configuration.md: Config, YAML, options, build tags.
• docs/outputs.md: output targets, custom writers, syslog, rotation.
• docs/slog.md: log/slog integration.
• docs/testing.md: checking logs in tests.
• docs/security.md: log injection, redaction, file permissions, HTTP handler.
• docs/research.md and docs/roadmap.md: research notes and plans.
• CHANGELOG.md: change history. AGENTS.md: contributor and agent rules.