Logrus

Logrus is a structured logging library for Go that is a drop-in replacement for the standard library’s log package. It lets you attach structured key-value fields to every log line instead of formatting messages by hand, and ships with both a colorized text formatter for local development and a JSON formatter for log aggregation tools like Logstash and Splunk.

The project is explicitly in maintenance mode: its API is stable and widely adopted across the Go ecosystem, but new feature development has stopped in favor of security fixes, bug fixes, and interoperability with Go’s newer structured logging package, log/slog. It remains one of the most widely used logging libraries in Go, with a large hook ecosystem for routing logs to syslog, exception trackers, and other destinations.

What You Get

• A stdlib-compatible Logger and set of package-level logging functions (Info, Warn, Error, Fatal, Panic, Trace, Debug)
• Structured fields via WithField/WithFields, letting you attach key-value context instead of formatting strings manually
• Built-in TextFormatter (colorized for TTYs) and JSONFormatter for machine-parseable log output
• A Hook interface for firing custom logic per log level, plus built-in hooks for syslog and a Writer for redirecting stdlib log output
• Seven log levels (Trace through Panic) with per-logger level filtering and IsLevelEnabled checks

Common Use Cases

• Structured application logging - Backend services attach request IDs, user IDs, and other context fields to every log line for easier querying in log aggregation tools
• Drop-in replacement for the stdlib logger - Teams migrate existing log.Print-based code to Logrus by swapping the import, gaining structured fields without rewriting call sites
• Log shipping to external systems - Applications use built-in or custom hooks to forward Error/Fatal/Panic-level entries to exception trackers, syslog, or metrics systems
• JSON logs for log aggregation - Services running behind Logstash or Splunk switch to JSONFormatter so their log output is directly machine-parseable

Under The Hood

Architecture

Logrus centers on two types: Logger, which owns the output writer, formatter, hooks, and level; and Entry, a snapshot of a single log event created via WithField(s) or WithContext and carried through Data map fields (logrus.go, logger.go, entry.go). Package-level functions in exported.go delegate to a singleton std *Logger, giving a convenient global-logger facade over the same instance-based API. Hooks are stored in a LevelHooks map keyed by level (hooks.go) and fired synchronously from entry.log, while output formatting is abstracted behind a single-method Formatter interface (formatter.go) implemented by TextFormatter and JSONFormatter. A sync.Pool recycles Entry objects and a BufferPool interface (buffer_pool.go) recycles byte buffers during formatting, and a mutexWrap (logger.go) serializes writes to Out. The design is a straightforward layered facade — Logger to Entry to Formatter/Hooks — with no dependency injection framework needed given the narrow domain.

Tech Stack

The module targets Go 1.23 and keeps its dependency surface minimal: golang.org/x/sys for terminal/TTY detection across platforms, stretchr/testify for assertions in tests, and a small indirect go.yaml.in/yaml/v3 dependency. There’s no web framework, ORM, or database layer since Logrus is a logging library, not an application framework. CI cross-compiles the package for every GOOS/GOARCH pair returned by go tool dist list, runs the test suite with the race detector across three Go versions (stable, oldstable, 1.23.x) on Linux, Windows, and macOS, and additionally verifies compatibility with TinyGo for constrained targets — an unusually broad build matrix for a library of this size.

Code Quality

Test coverage is extensive and close in size to the implementation itself — entry_test.go (657 lines) versus entry.go (567), logrus_test.go at 848 lines, and dedicated benchmark files (entry_bench_test.go, logger_bench_test.go, formatter_bench_test.go) alongside the unit tests. CI runs go test -race on every push and PR, and .golangci.yml enables a long list of strict linters — gosec, errorlint, testifylint, unparam, noctx, nilerr, exhaustive, and more — beyond the default set. Error handling favors explicit returned errors (ParseLevel, Hook.Fire) over panics except at the documented Fatal/Panic log levels, which intentionally call os.Exit/panic() as part of their contract. Naming and doc comments consistently use Go’s modern doc-linking syntax ([WithFields], [Entry.Data]), and example_*_test.go files double as runnable, verified documentation.

API Design The public API is deliberately small and mirrors the standard library logger, which is the main reason for its wide adoption — teams can alias log "github.com/sirupsen/logrus" and get structured fields with almost no code changes. WithField/WithFields return a chainable *Entry so context can be built up incrementally before a terminal call like .Info() or .Error() fires the write, and package-level functions (logrus.Info, logrus.WithFields, …) proxy to the same methods on a default instance so single-binary programs never need to construct a Logger explicitly. The tradeoff for that broad compatibility is that the library itself acknowledges, in its own README, that it is now in maintenance mode and that newer libraries (Zerolog, Zap, Apex) offer a more modern structured-logging design; Logrus optimizes for API stability and drop-in compatibility over new capabilities.