Guide · Open source
How to use logrus: structured logging in Go
Updated · written with AI from the project's own documentation and checked against our catalogue data
Logrus is a structured logging library for the Go programming language. It records messages with named fields, such as user IDs or request details, so tools can search and parse them. This guide shows you how to install it, log with fields, switch between text and JSON output, and decide whether it fits your project.
Logrussirupsen/logrus · ★ 25.8k · MIT Install options & downloads Quick start
- 1Install the package. Run go get github.com/sirupsen/logrus in your Go project. Go must already be installed.
- 2Import Logrus. Add import "github.com/sirupsen/logrus" to the file where you log, or use log "github.com/sirupsen/logrus" to replace the standard log import.
- 3Log with fields. Call logrus.WithFields with a map of named values, then call Info, Warn or another level method with the message.
- 4Choose a formatter. Call SetFormatter with JSONFormatter for log systems like Logstash or Splunk, or keep the default TextFormatter for logfmt-style output.
- 5Set output and level. Use SetOutput to choose where logs go and SetLevel to set the minimum severity that is logged.
- 6Reuse common fields. Store the result of WithFields in a variable and call log methods on it so shared fields appear on each line.
Install Logrus in a Go project
Logrus is installed as a Go package. The prerequisite is Go itself. Run the install command from your project directory, then import the package in your code.
- Prerequisite: Go
- Import path: github.com/sirupsen/logrus
go get github.com/sirupsen/logrusLog your first message with fields
The simplest way to use Logrus is the package-level exported logger. Use logrus.WithFields to attach named fields to a message, such as an animal name, then call a level method like Info. Fields make logs searchable, which the README recommends instead of long messages with values packed into the text.
Logrus is completely API compatible with the standard library logger, so you can replace your log imports with log "github.com/sirupsen/logrus" and keep your existing calls.
package main
import "github.com/sirupsen/logrus"
func main() {
logrus.WithFields(logrus.Fields{
"animal": "walrus",
}).Info("A walrus appears")
}Configure output format, destination and level
You can customize the package-level logger in an init function. The README shows three settings: a JSON formatter instead of the default text output, a destination other than stderr, and a minimum severity level so that only warnings and above are logged.
By default, the text formatter outputs logfmt-compatible lines when no TTY is attached. When a TTY is attached, output is color-coded. To keep plain text even on a TTY, set DisableColors and FullTimestamp on the TextFormatter.
- SetFormatter: choose JSON or text output
- SetOutput: any io.Writer, such as os.Stdout or a file
- SetLevel: for example log.WarnLevel to log only warnings and above
- Use a Logger instance with logrus.New() when you need to log to multiple places
func init() {
// Log as JSON instead of the default ASCII formatter.
log.SetFormatter(&log.JSONFormatter{})
// Output to stdout instead of the default stderr
log.SetOutput(os.Stdout)
// Only log the warning severity or above.
log.SetLevel(log.WarnLevel)
}Reuse fields with default entries
When the same fields, such as a request ID and user IP, should appear on every line in a request, create a logrus.Entry once and reuse it. Calls made on that entry include its fields automatically.
requestLogger := logger.WithFields(logrus.Fields{"request_id": request_id, "user_ip": user_ip})
requestLogger.Info("something happened on that request") // will log request_id and user_ip
requestLogger.Warn("something not great happened")Add the calling function and use hooks
Set SetReportCaller(true) to add the calling method as a field named method. The README warns that this adds measurable overhead, between 20 and 40 percent in its tests with Go 1.6 and 1.7, so measure it in your own environment with the benchmark command.
Hooks run for chosen logging levels. The README gives examples such as sending errors to an exception tracking service on Error, Fatal and Panic, sending info to StatsD, or logging to several places at once, such as syslog. Logrus includes built-in hooks in its hooks directory, and you can add your own in init.
- Hooks are attached per logging level
- Built-in hooks live in the hooks directory of the repository
logrus.SetReportCaller(true)What people use it for
- Logging request details such as request_id and user_ip on every line of a web request
- Sending JSON log lines to Logstash or Splunk for parsing and search
- Replacing standard library log calls in an existing Go codebase with named fields
- Sending errors to an exception tracking service through a hook on Error, Fatal and Panic
- Writing the same log output to several places at once, such as stdout and syslog
Frequently asked questions
Is Logrus free to use?
Logrus is released under the MIT licence, according to the project's listing. The MIT licence permits use in both open-source and commercial projects, but check the LICENSE file in the repository for the exact terms.
What do I need to install Logrus?
You need Go installed. Then run go get github.com/sirupsen/logrus in your project directory.
Is Logrus still actively developed?
The README says Logrus is in maintenance mode. The project focuses on security, bug fixes and performance improvements, and new features are not planned, apart from changes needed for interoperability such as with Go's log/slog.
What are good alternatives to Logrus?
The README names Zerolog, Zap and Apex as alternatives. The project's comparable list also includes Go's built-in slog package. For new projects that want active feature development, these are the options the README points to.
Why are my logs in text instead of JSON?
The default formatter is TextFormatter. Set logrus.SetFormatter(&logrus.JSONFormatter{}) to output JSON lines for tools like Logstash or Splunk.
Why does my output have colors, and how do I remove them?
Logrus color-codes output when a TTY is attached. To keep plain text, set TextFormatter with DisableColors set to true and FullTimestamp set to true.
Does Logrus slow down my application?
Logrus adds overhead when SetReportCaller is enabled, which the README measured at 20 to 40 percent in its tests. The README says the cost depends on the Go version, so run go test -bench=ReportCaller in your environment to check.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Logrus suits Go developers who already use it, teams that want a drop-in replacement for the standard log package with structured fields, and projects that send JSON logs to Logstash or Splunk. It is in maintenance mode, so new Go projects that need active feature development, or that need the lowest logging overhead, should consider Zerolog, Zap, Apex or the built-in slog package.
Install options & downloads