2017-05-15 10:45:16 +00:00
# Logrus <img src="http://i.imgur.com/hTeVwmJ.png" width="40" height="40" alt=":walrus:" class="emoji" title=":walrus:"/> [![Build Status](https://travis-ci.org/sirupsen/logrus.svg?branch=master)](https://travis-ci.org/sirupsen/logrus) [![GoDoc](https://godoc.org/github.com/sirupsen/logrus?status.svg)](https://godoc.org/github.com/sirupsen/logrus)
2013-10-16 19:27:10 +00:00
2014-03-11 00:07:22 +00:00
Logrus is a structured logger for Go (golang), completely API compatible with
2017-07-25 14:52:40 +00:00
the standard library logger.
2013-10-16 19:27:10 +00:00
2017-06-30 00:54:20 +00:00
**Seeing weird case-sensitive problems?** It's in the past been possible to
import Logrus as both upper- and lower-case. Due to the Go package environment,
this caused issues in the community and we needed a standard. Some environments
experienced problems with the upper-case variant, so the lower-case was decided.
2017-06-06 19:05:30 +00:00
Everything using `logrus` will need to use the lower-case:
`github.com/sirupsen/logrus` . Any package that isn't, should be changed.
2017-07-10 14:32:56 +00:00
To fix Glide, see [these
2017-06-06 20:59:16 +00:00
comments](https://github.com/sirupsen/logrus/issues/553#issuecomment-306591437).
2017-07-10 14:32:56 +00:00
For an in-depth explanation of the casing issue, see [this
comment](https://github.com/sirupsen/logrus/issues/570#issuecomment-313933276).
2017-06-06 19:05:30 +00:00
2017-07-06 13:44:07 +00:00
**Are you interested in assisting in maintaining Logrus?** Currently I have a
lot of obligations, and I am unable to provide Logrus with the maintainership it
needs. If you'd like to help, please reach out to me at `simon at author's
username dot com`.
2014-03-11 00:00:07 +00:00
Nicely color-coded in development (when a TTY is attached, otherwise just
plain text):
2014-03-10 23:59:18 +00:00
2014-03-11 00:00:07 +00:00
![Colored ](http://i.imgur.com/PY7qMwd.png )
2014-03-10 23:59:18 +00:00
2016-02-16 03:41:25 +00:00
With `log.SetFormatter(&log.JSONFormatter{})` , for easy parsing by logstash
2014-03-11 00:01:07 +00:00
or Splunk:
2014-03-10 23:59:18 +00:00
```json
{"animal":"walrus","level":"info","msg":"A group of walrus emerges from the
2014-03-14 20:17:18 +00:00
ocean","size":10,"time":"2014-03-10 19:57:38.562264131 -0400 EDT"}
2014-03-11 00:06:39 +00:00
{"level":"warning","msg":"The group's number increased tremendously!",
"number":122,"omg":true,"time":"2014-03-10 19:57:38.562471297 -0400 EDT"}
{"animal":"walrus","level":"info","msg":"A giant walrus appears!",
2014-03-14 20:17:18 +00:00
"size":10,"time":"2014-03-10 19:57:38.562500591 -0400 EDT"}
2014-03-11 00:06:39 +00:00
{"animal":"walrus","level":"info","msg":"Tremendously sized cow enters the ocean.",
2014-03-14 20:17:18 +00:00
"size":9,"time":"2014-03-10 19:57:38.562527896 -0400 EDT"}
2014-03-11 00:06:39 +00:00
{"level":"fatal","msg":"The ice breaks!","number":100,"omg":true,
"time":"2014-03-10 19:57:38.562543128 -0400 EDT"}
2014-03-10 23:59:18 +00:00
```
2016-02-16 03:41:25 +00:00
With the default `log.SetFormatter(&log.TextFormatter{})` when a TTY is not
2014-04-24 00:21:38 +00:00
attached, the output is compatible with the
2015-01-10 00:13:34 +00:00
[logfmt ](http://godoc.org/github.com/kr/logfmt ) format:
2014-03-14 17:02:15 +00:00
```text
2015-03-26 23:04:45 +00:00
time="2015-03-26T01:27:38-04:00" level=debug msg="Started observing beach" animal=walrus number=8
time="2015-03-26T01:27:38-04:00" level=info msg="A group of walrus emerges from the ocean" animal=walrus size=10
time="2015-03-26T01:27:38-04:00" level=warning msg="The group's number increased tremendously!" number=122 omg=true
time="2015-03-26T01:27:38-04:00" level=debug msg="Temperature changes" temperature=-4
time="2015-03-26T01:27:38-04:00" level=panic msg="It's over 9000!" animal=orca size=9009
time="2015-03-26T01:27:38-04:00" level=fatal msg="The ice breaks!" err=& {0x2082280c0 map[animal:orca size:9009] 2015-03-26 01:27:38.441574009 -0400 EDT panic It's over 9000!} number=100 omg=true
exit status 1
2014-03-14 17:02:15 +00:00
```
2017-05-12 19:09:01 +00:00
#### Case-sensitivity
The organization's name was changed to lower-case--and this will not be changed
back. If you are getting import conflicts due to case sensitivity, please use
the lower-case import: `github.com/sirupsen/logrus` .
2014-04-13 21:51:46 +00:00
#### Example
2014-07-27 02:46:08 +00:00
The simplest way to use Logrus is simply the package-level exported logger:
2014-04-13 21:51:46 +00:00
```go
package main
import (
2017-05-11 10:19:16 +00:00
log "github.com/sirupsen/logrus"
2014-04-13 21:51:46 +00:00
)
2014-07-27 02:46:08 +00:00
func main() {
2016-06-01 11:32:10 +00:00
log.WithFields(log.Fields{
2014-07-27 02:51:23 +00:00
"animal": "walrus",
2014-07-27 02:46:08 +00:00
}).Info("A walrus appears")
}
```
Note that it's completely api-compatible with the stdlib logger, so you can
2017-05-11 10:19:16 +00:00
replace your `log` imports everywhere with `log "github.com/sirupsen/logrus"`
2014-07-27 02:46:08 +00:00
and you'll now have the flexibility of Logrus. You can customize it all you
want:
```go
package main
import (
"os"
2017-05-11 10:19:16 +00:00
log "github.com/sirupsen/logrus"
2014-07-27 02:46:08 +00:00
)
2014-04-13 21:51:46 +00:00
func init() {
2014-07-27 02:46:08 +00:00
// Log as JSON instead of the default ASCII formatter.
2014-08-06 03:09:02 +00:00
log.SetFormatter(& log.JSONFormatter{})
2014-07-27 02:46:08 +00:00
2017-02-07 00:16:20 +00:00
// Output to stdout instead of the default stderr
// Can be any io.Writer, see below for File example
2016-12-02 00:34:47 +00:00
log.SetOutput(os.Stdout)
2014-07-27 02:46:08 +00:00
// Only log the warning severity or above.
2014-08-06 03:09:02 +00:00
log.SetLevel(log.WarnLevel)
2014-04-13 21:51:46 +00:00
}
func main() {
2014-07-27 02:51:23 +00:00
log.WithFields(log.Fields{
2014-04-13 21:51:46 +00:00
"animal": "walrus",
"size": 10,
}).Info("A group of walrus emerges from the ocean")
2014-07-27 02:51:23 +00:00
log.WithFields(log.Fields{
2014-04-13 21:51:46 +00:00
"omg": true,
"number": 122,
}).Warn("The group's number increased tremendously!")
2014-07-27 02:51:23 +00:00
log.WithFields(log.Fields{
2014-04-13 21:51:46 +00:00
"omg": true,
"number": 100,
}).Fatal("The ice breaks!")
2015-03-31 15:24:31 +00:00
2015-03-31 15:30:41 +00:00
// A common pattern is to re-use fields between logging statements by re-using
// the logrus.Entry returned from WithFields()
2015-03-31 15:24:31 +00:00
contextLogger := log.WithFields(log.Fields{
"common": "this is a common field",
"other": "I also should be logged always",
})
contextLogger.Info("I'll be logged with common and other field")
contextLogger.Info("Me too")
2014-04-13 21:51:46 +00:00
}
```
2014-07-27 02:46:08 +00:00
For more advanced usage such as logging to multiple locations from the same
application, you can also create an instance of the `logrus` Logger:
2014-07-23 20:48:53 +00:00
2014-07-27 02:46:08 +00:00
```go
package main
import (
2017-02-24 03:58:06 +00:00
"os"
2017-05-11 10:19:16 +00:00
"github.com/sirupsen/logrus"
2014-07-27 02:46:08 +00:00
)
// Create a new instance of the logger. You can have any number of instances.
var log = logrus.New()
func main() {
// The API for setting attributes is a little different than the package level
// exported logger. See Godoc.
2017-02-07 00:16:20 +00:00
log.Out = os.Stdout
// You could set this to any `io.Writer` such as a file
// file, err := os.OpenFile("logrus.log", os.O_CREATE|os.O_WRONLY, 0666)
// if err == nil {
// log.Out = file
// } else {
// log.Info("Failed to log to file, using default stderr")
// }
2014-07-27 02:46:08 +00:00
2014-10-27 21:22:57 +00:00
log.WithFields(logrus.Fields{
2014-07-27 02:46:08 +00:00
"animal": "walrus",
"size": 10,
}).Info("A group of walrus emerges from the ocean")
}
```
2014-07-23 20:48:53 +00:00
2014-03-07 02:20:13 +00:00
#### Fields
2013-10-16 19:27:10 +00:00
2017-02-10 15:30:30 +00:00
Logrus encourages careful, structured logging through logging fields instead of
2014-04-24 00:21:38 +00:00
long, unparseable error messages. For example, instead of: `log.Fatalf("Failed
to send event %s to topic %s with key %d")`, you should log the much more
discoverable:
2013-10-16 19:27:10 +00:00
2014-03-07 02:20:13 +00:00
```go
2014-07-27 02:51:23 +00:00
log.WithFields(log.Fields{
2014-03-07 02:20:13 +00:00
"event": event,
"topic": topic,
2014-07-23 20:48:53 +00:00
"key": key,
2014-03-07 02:20:13 +00:00
}).Fatal("Failed to send event")
```
We've found this API forces you to think about logging in a way that produces
2014-03-11 15:01:18 +00:00
much more useful logging messages. We've been in countless situations where just
a single added field to a log statement that was already there would've saved us
hours. The `WithFields` call is optional.
2014-03-07 02:20:13 +00:00
2014-03-07 02:26:05 +00:00
In general, with Logrus using any of the `printf` -family functions should be
2014-04-24 00:21:38 +00:00
seen as a hint you should add a field, however, you can still use the
2014-03-07 02:26:05 +00:00
`printf` -family functions with Logrus.
2017-02-07 18:34:08 +00:00
#### Default Fields
Often it's helpful to have fields _always_ attached to log statements in an
application or parts of one. For example, you may want to always log the
`request_id` and `user_ip` in the context of a request. Instead of writing
`log.WithFields(log.Fields{"request_id": request_id, "user_ip": user_ip})` on
every line, you can create a `logrus.Entry` to pass around instead:
```go
2017-02-15 00:37:12 +00:00
requestLogger := log.WithFields(log.Fields{"request_id": request_id, "user_ip": user_ip})
2017-02-07 18:34:08 +00:00
requestLogger.Info("something happened on that request") # will log request_id and user_ip
requestLogger.Warn("something not great happened")
```
2014-03-07 02:20:13 +00:00
#### Hooks
2013-10-16 19:27:10 +00:00
2014-03-07 02:26:05 +00:00
You can add hooks for logging levels. For example to send errors to an exception
2014-04-24 00:21:38 +00:00
tracking service on `Error` , `Fatal` and `Panic` , info to StatsD or log to
multiple places simultaneously, e.g. syslog.
2013-10-16 19:27:10 +00:00
2015-03-10 18:01:14 +00:00
Logrus comes with [built-in hooks ](hooks/ ). Add those, or your custom hook, in
`init` :
2014-04-13 22:17:20 +00:00
```go
import (
2017-05-11 10:19:16 +00:00
log "github.com/sirupsen/logrus"
2018-02-05 20:59:23 +00:00
"gopkg.in/gemnasium/logrus-airbrake-hook.v2" // the package is named "airbrake"
2017-05-11 10:19:16 +00:00
logrus_syslog "github.com/sirupsen/logrus/hooks/syslog"
2014-11-23 02:09:39 +00:00
"log/syslog"
2014-04-13 22:17:20 +00:00
)
func init() {
2015-10-06 18:28:31 +00:00
// Use the Airbrake hook to report errors that have Error severity or above to
// an exception tracker. You can create custom hooks, see the Hooks section.
log.AddHook(airbrake.NewHook(123, "xyz", "production"))
2014-11-23 02:09:39 +00:00
hook, err := logrus_syslog.NewSyslogHook("udp", "localhost:514", syslog.LOG_INFO, "")
if err != nil {
log.Error("Unable to connect to local syslog daemon")
} else {
log.AddHook(hook)
}
2014-04-13 22:17:20 +00:00
}
```
2015-09-09 13:55:50 +00:00
Note: Syslog hook also support connecting to local syslog (Ex. "/dev/log" or "/var/run/syslog" or "/var/run/log"). For the detail, please check the [syslog hook README ](hooks/syslog/README.md ).
2014-04-13 22:17:20 +00:00
2015-03-27 13:43:24 +00:00
| Hook | Description |
| ----- | ----------- |
2015-10-06 18:28:31 +00:00
| [Airbrake "legacy" ](https://github.com/gemnasium/logrus-airbrake-legacy-hook ) | Send errors to an exception tracking service compatible with the Airbrake API V2. Uses [`airbrake-go` ](https://github.com/tobi/airbrake-go ) behind the scenes. |
2017-02-07 00:40:31 +00:00
| [Airbrake ](https://github.com/gemnasium/logrus-airbrake-hook ) | Send errors to the Airbrake API V3. Uses the official [`gobrake` ](https://github.com/airbrake/gobrake ) behind the scenes. |
2017-02-07 00:44:51 +00:00
| [Amazon Kinesis ](https://github.com/evalphobia/logrus_kinesis ) | Hook for logging to [Amazon Kinesis ](https://aws.amazon.com/kinesis/ ) |
2017-02-07 00:40:31 +00:00
| [Amqp-Hook ](https://github.com/vladoatanasov/logrus_amqp ) | Hook for logging to Amqp broker (Like RabbitMQ) |
2018-01-30 16:00:33 +00:00
| [Application Insights ](https://github.com/jjcollinge/logrus-appinsights ) | Hook for logging to [Application Insights ](https://azure.microsoft.com/en-us/services/application-insights/ )
2017-08-20 02:47:38 +00:00
| [AzureTableHook ](https://github.com/kpfaulkner/azuretablehook/ ) | Hook for logging to Azure Table Storage|
2015-10-22 20:20:45 +00:00
| [Bugsnag ](https://github.com/Shopify/logrus-bugsnag/blob/master/bugsnag.go ) | Send errors to the Bugsnag exception tracking service. |
2018-02-16 13:50:54 +00:00
| [ClickHouse ](https://github.com/oxgrouby/logrus-clickhouse-hook ) | Send logs to [ClickHouse ](https://clickhouse.yandex/ ) |
2017-02-07 00:40:31 +00:00
| [DeferPanic ](https://github.com/deferpanic/dp-logrus ) | Hook for logging to DeferPanic |
2017-02-17 14:09:07 +00:00
| [Discordrus ](https://github.com/kz/discordrus ) | Hook for logging to [Discord ](https://discordapp.com/ ) |
2017-02-07 00:40:31 +00:00
| [ElasticSearch ](https://github.com/sohlich/elogrus ) | Hook for logging to ElasticSearch|
2017-05-02 17:47:34 +00:00
| [Firehose ](https://github.com/beaubrewer/logrus_firehose ) | Hook for logging to [Amazon Firehose ](https://aws.amazon.com/kinesis/firehose/ )
2017-02-07 00:40:31 +00:00
| [Fluentd ](https://github.com/evalphobia/logrus_fluent ) | Hook for logging to fluentd |
| [Go-Slack ](https://github.com/multiplay/go-slack ) | Hook for logging to [Slack ](https://slack.com ) |
| [Graylog ](https://github.com/gemnasium/logrus-graylog-hook ) | Hook for logging to [Graylog ](http://graylog2.org/ ) |
2015-03-27 13:43:24 +00:00
| [Hiprus ](https://github.com/nubo/hiprus ) | Send errors to a channel in hipchat. |
2017-02-07 00:40:31 +00:00
| [Honeybadger ](https://github.com/agonzalezro/logrus_honeybadger ) | Hook for sending exceptions to Honeybadger |
| [InfluxDB ](https://github.com/Abramovic/logrus_influxdb ) | Hook for logging to influxdb |
2017-05-03 16:23:24 +00:00
| [Influxus ](http://github.com/vlad-doru/influxus ) | Hook for concurrently logging to [InfluxDB ](http://influxdata.com/ ) |
2015-03-27 13:43:24 +00:00
| [Journalhook ](https://github.com/wercker/journalhook ) | Hook for logging to `systemd-journald` |
2017-08-17 07:33:45 +00:00
| [KafkaLogrus ](https://github.com/tracer0tong/kafkalogrus ) | Hook for logging to Kafka |
2018-02-11 15:37:38 +00:00
| [Kafka REST Proxy ](https://github.com/Nordstrom/logrus-kafka-rest-proxy ) | Hook for logging to [Kafka REST Proxy ](https://docs.confluent.io/current/kafka-rest/docs ) |
2015-06-02 22:36:57 +00:00
| [LFShook ](https://github.com/rifflock/lfshook ) | Hook for logging to the local filesystem |
2017-10-26 18:58:09 +00:00
| [Logbeat ](https://github.com/macandmia/logbeat ) | Hook for logging to [Opbeat ](https://opbeat.com/ ) |
2017-02-07 00:44:51 +00:00
| [Logentries ](https://github.com/jcftang/logentriesrus ) | Hook for logging to [Logentries ](https://logentries.com/ ) |
2017-02-07 00:40:31 +00:00
| [Logentrus ](https://github.com/puddingfactory/logentrus ) | Hook for logging to [Logentries ](https://logentries.com/ ) |
| [Logmatic.io ](https://github.com/logmatic/logmatic-go ) | Hook for logging to [Logmatic.io ](http://logmatic.io/ ) |
| [Logrusly ](https://github.com/sebest/logrusly ) | Send logs to [Loggly ](https://www.loggly.com/ ) |
| [Logstash ](https://github.com/bshuster-repo/logrus-logstash-hook ) | Hook for logging to [Logstash ](https://www.elastic.co/products/logstash ) |
2015-06-10 09:09:59 +00:00
| [Mail ](https://github.com/zbindenren/logrus_mail ) | Hook for sending exceptions via mail |
2017-05-18 10:03:42 +00:00
| [Mattermost ](https://github.com/shuLhan/mattermost-integration/tree/master/hooks/logrus ) | Hook for logging to [Mattermost ](https://mattermost.com/ ) |
2015-08-27 01:54:11 +00:00
| [Mongodb ](https://github.com/weekface/mgorus ) | Hook for logging to mongodb |
2017-02-07 00:40:31 +00:00
| [NATS-Hook ](https://github.com/rybit/nats_logrus_hook ) | Hook for logging to [NATS ](https://nats.io ) |
2015-10-27 09:58:00 +00:00
| [Octokit ](https://github.com/dorajistyle/logrus-octokit-hook ) | Hook for logging to github via octokit |
2017-02-07 00:40:31 +00:00
| [Papertrail ](https://github.com/polds/logrus-papertrail-hook ) | Send errors to the [Papertrail ](https://papertrailapp.com ) hosted logging service via UDP. |
| [PostgreSQL ](https://github.com/gemnasium/logrus-postgresql-hook ) | Send logs to [PostgreSQL ](http://postgresql.org ) |
2017-10-03 14:08:46 +00:00
| [Promrus ](https://github.com/weaveworks/promrus ) | Expose number of log messages as [Prometheus ](https://prometheus.io/ ) metrics |
2017-02-07 00:40:31 +00:00
| [Pushover ](https://github.com/toorop/logrus_pushover ) | Send error via [Pushover ](https://pushover.net ) |
| [Raygun ](https://github.com/squirkle/logrus-raygun-hook ) | Hook for logging to [Raygun.io ](http://raygun.io/ ) |
2016-01-26 20:01:36 +00:00
| [Redis-Hook ](https://github.com/rogierlommers/logrus-redis-hook ) | Hook for logging to a ELK stack (through Redis) |
2017-02-07 00:40:31 +00:00
| [Rollrus ](https://github.com/heroku/rollrus ) | Hook for sending errors to rollbar |
2016-09-18 19:42:16 +00:00
| [Scribe ](https://github.com/sagar8192/logrus-scribe-hook ) | Hook for logging to [Scribe ](https://github.com/facebookarchive/scribe )|
2017-02-07 00:40:31 +00:00
| [Sentry ](https://github.com/evalphobia/logrus_sentry ) | Send errors to the Sentry error logging and aggregation service. |
| [Slackrus ](https://github.com/johntdyer/slackrus ) | Hook for Slack chat. |
2017-02-07 00:44:51 +00:00
| [Stackdriver ](https://github.com/knq/sdhook ) | Hook for logging to [Google Stackdriver ](https://cloud.google.com/logging/ ) |
2017-02-07 00:40:31 +00:00
| [Sumorus ](https://github.com/doublefree/sumorus ) | Hook for logging to [SumoLogic ](https://www.sumologic.com/ )|
2017-07-06 22:21:34 +00:00
| [Syslog ](https://github.com/sirupsen/logrus/blob/master/hooks/syslog/syslog.go ) | Send errors to remote syslog server. Uses standard library `log/syslog` behind the scenes. |
2017-05-25 00:53:41 +00:00
| [Syslog TLS ](https://github.com/shinji62/logrus-syslog-ng ) | Send errors to remote syslog server with TLS support. |
2017-08-07 21:36:23 +00:00
| [Telegram ](https://github.com/rossmcdonald/telegram_hook ) | Hook for logging errors to [Telegram ](https://telegram.org/ ) |
2017-02-07 00:44:51 +00:00
| [TraceView ](https://github.com/evalphobia/logrus_appneta ) | Hook for logging to [AppNeta TraceView ](https://www.appneta.com/products/traceview/ ) |
2017-02-07 00:40:31 +00:00
| [Typetalk ](https://github.com/dragon3/logrus-typetalk-hook ) | Hook for logging to [Typetalk ](https://www.typetalk.in/ ) |
2017-03-22 20:32:29 +00:00
| [SQS-Hook ](https://github.com/tsarpaul/logrus_sqs ) | Hook for logging to [Amazon Simple Queue Service (SQS) ](https://aws.amazon.com/sqs/ ) |
2015-02-19 18:51:02 +00:00
2014-03-07 02:20:13 +00:00
#### Level logging
2013-10-16 19:27:10 +00:00
2014-03-11 00:06:39 +00:00
Logrus has six logging levels: Debug, Info, Warning, Error, Fatal and Panic.
2013-10-16 19:27:10 +00:00
2014-02-24 01:19:34 +00:00
```go
2014-03-07 02:49:10 +00:00
log.Debug("Useful debugging information.")
2014-03-07 02:20:13 +00:00
log.Info("Something noteworthy happened!")
log.Warn("You should probably take a look at this.")
log.Error("Something failed but I'm not quitting.")
2014-03-12 12:00:18 +00:00
// Calls os.Exit(1) after logging
2014-03-07 02:20:13 +00:00
log.Fatal("Bye.")
2014-03-12 12:00:18 +00:00
// Calls panic() after logging
2014-03-07 02:20:13 +00:00
log.Panic("I'm bailing.")
```
2014-03-11 00:06:39 +00:00
You can set the logging level on a `Logger` , then it will only log entries with
that severity or anything above it:
2014-03-07 02:49:10 +00:00
```go
2014-03-11 00:06:39 +00:00
// Will log anything that is info or above (warn, error, fatal, panic). Default.
2014-07-27 02:51:23 +00:00
log.SetLevel(log.InfoLevel)
2014-03-07 02:49:10 +00:00
```
2014-07-27 02:23:41 +00:00
It may be useful to set `log.Level = logrus.DebugLevel` in a debug or verbose
2014-03-11 00:06:39 +00:00
environment if your application has that.
2014-03-07 02:20:13 +00:00
#### Entries
Besides the fields added with `WithField` or `WithFields` some fields are
automatically added to all logging events:
1. `time` . The timestamp when the entry was created.
2. `msg` . The logging message passed to `{Info,Warn,Error,Fatal,Panic}` after
the `AddFields` call. E.g. `Failed to send event.`
3. `level` . The logging level. E.g. `info` .
#### Environments
2014-03-14 19:21:54 +00:00
Logrus has no notion of environment.
2014-03-11 00:06:39 +00:00
If you wish for hooks and formatters to only be used in specific environments,
you should handle that yourself. For example, if your application has a global
variable `Environment` , which is a string representation of the environment you
could do:
2014-03-07 02:20:13 +00:00
```go
2014-07-27 02:46:08 +00:00
import (
2017-05-11 10:19:16 +00:00
log "github.com/sirupsen/logrus"
2014-07-27 02:46:08 +00:00
)
2014-03-07 02:20:13 +00:00
init() {
// do something here to set environment depending on an environment variable
// or command-line flag
if Environment == "production" {
2015-08-18 18:15:02 +00:00
log.SetFormatter(& log.JSONFormatter{})
2014-03-07 02:20:13 +00:00
} else {
// The TextFormatter is default, you don't actually have to do this.
2015-05-12 16:27:20 +00:00
log.SetFormatter(& log.TextFormatter{})
2014-03-07 02:20:13 +00:00
}
2013-10-16 19:27:10 +00:00
}
```
2014-02-24 01:19:34 +00:00
2014-03-11 00:06:39 +00:00
This configuration is how `logrus` was intended to be used, but JSON in
production is mostly only useful if you do log aggregation with tools like
Splunk or Logstash.
#### Formatters
2014-03-07 02:20:13 +00:00
2014-03-14 19:21:54 +00:00
The built-in logging formatters are:
2014-03-07 02:20:13 +00:00
* `logrus.TextFormatter` . Logs the event in colors if stdout is a tty, otherwise
2014-03-07 17:51:29 +00:00
without colors.
2014-03-16 21:27:31 +00:00
* *Note:* to force colored output when there is no TTY, set the `ForceColors`
2014-09-13 18:55:08 +00:00
field to `true` . To force no colored output even if there is a TTY set the
2017-02-07 00:51:07 +00:00
`DisableColors` field to `true` . For Windows, see
[github.com/mattn/go-colorable ](https://github.com/mattn/go-colorable ).
2017-01-24 12:05:25 +00:00
* When colors are enabled, levels are truncated to 4 characters by default. To disable
truncation set the `DisableLevelTruncation` field to `true` .
2017-02-07 00:51:07 +00:00
* All options are listed in the [generated docs ](https://godoc.org/github.com/sirupsen/logrus#TextFormatter ).
2014-03-07 17:51:29 +00:00
* `logrus.JSONFormatter` . Logs fields as JSON.
2017-02-07 00:51:07 +00:00
* All options are listed in the [generated docs ](https://godoc.org/github.com/sirupsen/logrus#JSONFormatter ).
2015-02-20 16:02:11 +00:00
2014-03-14 19:21:54 +00:00
Third party logging formatters:
2017-11-14 21:58:00 +00:00
* [`FluentdFormatter` ](https://github.com/joonix/log ). Formats entries that can be parsed by Kubernetes and Google Container Engine.
2016-07-12 20:21:34 +00:00
* [`logstash` ](https://github.com/bshuster-repo/logrus-logstash-hook ). Logs fields as [Logstash ](http://logstash.net ) Events.
2015-10-26 23:53:47 +00:00
* [`prefixed` ](https://github.com/x-cray/logrus-prefixed-formatter ). Displays log entry source along with alternative layout.
* [`zalgo` ](https://github.com/aybabtme/logzalgo ). Invoking the P͉̫o̳̼̊w̖͈̰͎e̬͔̭͂r͚̼̹̲ ̫͓͉̳͈ō̠͕͖̚f̝͍̠ ͕̲̞͖͑Z̖̫̤̫ͪa͉̬͈̗l͖͎g̳̥o̰̥̅!̣͔̲̻͊̄ ̙̘̦̹̦.
2014-03-14 19:21:54 +00:00
2014-03-11 00:06:39 +00:00
You can define your formatter by implementing the `Formatter` interface,
requiring a `Format` method. `Format` takes an `*Entry` . `entry.Data` is a
`Fields` type (`map[string]interface{}`) with all your fields as well as the
default ones (see Entries section above):
2014-03-07 02:20:13 +00:00
```go
2014-03-10 23:27:19 +00:00
type MyJSONFormatter struct {
}
2014-07-27 02:46:08 +00:00
log.SetFormatter(new(MyJSONFormatter))
2014-03-10 23:27:19 +00:00
2015-09-04 10:02:14 +00:00
func (f *MyJSONFormatter) Format(entry *Entry) ([]byte, error) {
2014-07-27 01:26:04 +00:00
// Note this doesn't include Time, Level and Message which are available on
// the Entry. Consult `godoc` on information about those fields or read the
// source of the official loggers.
2014-03-10 23:27:19 +00:00
serialized, err := json.Marshal(entry.Data)
if err != nil {
return nil, fmt.Errorf("Failed to marshal fields to JSON, %v", err)
}
return append(serialized, '\n'), nil
}
2014-03-07 02:20:13 +00:00
```
2014-03-11 01:15:25 +00:00
2015-01-31 19:07:15 +00:00
#### Logger as an `io.Writer`
2015-06-30 21:20:00 +00:00
Logrus can be transformed into an `io.Writer` . That writer is the end of an `io.Pipe` and it is your responsibility to close it.
2015-01-31 19:07:15 +00:00
```go
w := logger.Writer()
defer w.Close()
srv := http.Server{
// create a stdlib log.Logger that writes to
// logrus.Logger.
ErrorLog: log.New(w, "", 0),
}
```
Each line written to that writer will be printed the usual way, using formatters
and hooks. The level for those entries is `info` .
2017-02-07 00:56:22 +00:00
This means that we can override the standard library logger easily:
2017-02-07 11:40:37 +00:00
```go
2017-02-07 00:56:22 +00:00
logger := logrus.New()
logger.Formatter = & logrus.JSONFormatter{}
// Use logrus for standard log output
// Note that `log` here references stdlib's log
// Not logrus imported under the name `log` .
log.SetOutput(logger.Writer())
2017-02-07 11:40:37 +00:00
```
2017-02-07 00:56:22 +00:00
2014-07-27 01:46:04 +00:00
#### Rotation
Log rotation is not provided with Logrus. Log rotation should be done by an
2015-02-10 08:49:34 +00:00
external program (like `logrotate(8)` ) that can compress and delete old log
2014-07-27 01:46:04 +00:00
entries. It should not be a feature of the application-level logger.
2015-10-19 06:19:45 +00:00
#### Tools
| Tool | Description |
| ---- | ----------- |
2015-11-16 10:22:07 +00:00
|[Logrus Mate](https://github.com/gogap/logrus_mate)|Logrus mate is a tool for Logrus to manage loggers, you can initial logger's level, hook and formatter by config file, the logger will generated with different config at different environment.|
2017-03-07 16:02:20 +00:00
|[Logrus Viper Helper](https://github.com/heirko/go-contrib/tree/master/logrusHelper)|An Helper around Logrus to wrap with spf13/Viper to load configuration with fangs! And to simplify Logrus configuration use some behavior of [Logrus Mate ](https://github.com/gogap/logrus_mate ). [sample ](https://github.com/heirko/iris-contrib/blob/master/middleware/logrus-logger/example ) |
2014-07-27 01:46:04 +00:00
2015-10-09 14:07:29 +00:00
#### Testing
Logrus has a built in facility for asserting the presence of log messages. This is implemented through the `test` hook and provides:
* decorators for existing logger (`test.NewLocal` and `test.NewGlobal` ) which basically just add the `test` hook
* a test logger (`test.NewNullLogger`) that just records log messages (and does not output any):
```go
2017-05-12 19:15:51 +00:00
import(
"github.com/sirupsen/logrus"
2017-06-13 18:28:47 +00:00
"github.com/sirupsen/logrus/hooks/test"
2017-05-12 19:15:51 +00:00
"github.com/stretchr/testify/assert"
"testing"
2017-05-12 18:51:38 +00:00
)
2015-10-09 14:07:29 +00:00
2017-05-12 19:15:51 +00:00
func TestSomething(t*testing.T){
2017-06-13 18:28:47 +00:00
logger, hook := test.NewNullLogger()
2017-05-12 19:15:51 +00:00
logger.Error("Helloerror")
2015-10-09 14:07:29 +00:00
2017-05-12 19:15:51 +00:00
assert.Equal(t, 1, len(hook.Entries))
assert.Equal(t, logrus.ErrorLevel, hook.LastEntry().Level)
assert.Equal(t, "Helloerror", hook.LastEntry().Message)
2017-05-12 18:51:38 +00:00
hook.Reset()
2017-05-12 19:15:51 +00:00
assert.Nil(t, hook.LastEntry())
2017-05-12 18:51:38 +00:00
}
2015-10-09 14:07:29 +00:00
```
2016-07-16 02:56:31 +00:00
#### Fatal handlers
Logrus can register one or more functions that will be called when any `fatal`
level message is logged. The registered handlers will be executed before
logrus performs a `os.Exit(1)` . This behavior may be helpful if callers need
to gracefully shutdown. Unlike a `panic("Something went wrong...")` call which can be intercepted with a deferred `recover` a call to `os.Exit(1)` can not be intercepted.
```
...
handler := func() {
// gracefully shutdown something...
}
logrus.RegisterExitHandler(handler)
...
```
2016-08-10 17:39:36 +00:00
2016-11-29 18:52:28 +00:00
#### Thread safety
2016-08-10 17:39:36 +00:00
2018-03-10 05:57:56 +00:00
By default, Logger is protected by a mutex for concurrent writes. The mutex is held when calling hooks and writing logs.
2016-08-10 17:39:36 +00:00
If you are sure such locking is not needed, you can call logger.SetNoLock() to disable the locking.
Situation when locking is not needed includes:
* You have no hooks registered, or hooks calling is already thread-safe.
* Writing to logger.Out is already thread-safe, for example:
1) logger.Out is protected by locks.
2) logger.Out is a os.File handler opened with `O_APPEND` flag, and every write is smaller than 4k. (This allow multi-thread/multi-process writing)
(Refer to http://www.notthewizard.com/2014/06/17/are-files-appends-really-atomic/)