1 # 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)
3 Logrus is a structured logger for Go (golang), completely API compatible with
4 the standard library logger.
6 **Seeing weird case-sensitive problems?** It's in the past been possible to
7 import Logrus as both upper- and lower-case. Due to the Go package environment,
8 this caused issues in the community and we needed a standard. Some environments
9 experienced problems with the upper-case variant, so the lower-case was decided.
10 Everything using `logrus` will need to use the lower-case:
11 `github.com/sirupsen/logrus`. Any package that isn't, should be changed.
13 To fix Glide, see [these
14 comments](https://github.com/sirupsen/logrus/issues/553#issuecomment-306591437).
15 For an in-depth explanation of the casing issue, see [this
16 comment](https://github.com/sirupsen/logrus/issues/570#issuecomment-313933276).
18 **Are you interested in assisting in maintaining Logrus?** Currently I have a
19 lot of obligations, and I am unable to provide Logrus with the maintainership it
20 needs. If you'd like to help, please reach out to me at `simon at author's
23 Nicely color-coded in development (when a TTY is attached, otherwise just
26 ![Colored](http://i.imgur.com/PY7qMwd.png)
28 With `log.SetFormatter(&log.JSONFormatter{})`, for easy parsing by logstash
32 {"animal":"walrus","level":"info","msg":"A group of walrus emerges from the
33 ocean","size":10,"time":"2014-03-10 19:57:38.562264131 -0400 EDT"}
35 {"level":"warning","msg":"The group's number increased tremendously!",
36 "number":122,"omg":true,"time":"2014-03-10 19:57:38.562471297 -0400 EDT"}
38 {"animal":"walrus","level":"info","msg":"A giant walrus appears!",
39 "size":10,"time":"2014-03-10 19:57:38.562500591 -0400 EDT"}
41 {"animal":"walrus","level":"info","msg":"Tremendously sized cow enters the ocean.",
42 "size":9,"time":"2014-03-10 19:57:38.562527896 -0400 EDT"}
44 {"level":"fatal","msg":"The ice breaks!","number":100,"omg":true,
45 "time":"2014-03-10 19:57:38.562543128 -0400 EDT"}
48 With the default `log.SetFormatter(&log.TextFormatter{})` when a TTY is not
49 attached, the output is compatible with the
50 [logfmt](http://godoc.org/github.com/kr/logfmt) format:
53 time="2015-03-26T01:27:38-04:00" level=debug msg="Started observing beach" animal=walrus number=8
54 time="2015-03-26T01:27:38-04:00" level=info msg="A group of walrus emerges from the ocean" animal=walrus size=10
55 time="2015-03-26T01:27:38-04:00" level=warning msg="The group's number increased tremendously!" number=122 omg=true
56 time="2015-03-26T01:27:38-04:00" level=debug msg="Temperature changes" temperature=-4
57 time="2015-03-26T01:27:38-04:00" level=panic msg="It's over 9000!" animal=orca size=9009
58 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
64 The organization's name was changed to lower-case--and this will not be changed
65 back. If you are getting import conflicts due to case sensitivity, please use
66 the lower-case import: `github.com/sirupsen/logrus`.
70 The simplest way to use Logrus is simply the package-level exported logger:
76 log "github.com/sirupsen/logrus"
80 log.WithFields(log.Fields{
82 }).Info("A walrus appears")
86 Note that it's completely api-compatible with the stdlib logger, so you can
87 replace your `log` imports everywhere with `log "github.com/sirupsen/logrus"`
88 and you'll now have the flexibility of Logrus. You can customize it all you
96 log "github.com/sirupsen/logrus"
100 // Log as JSON instead of the default ASCII formatter.
101 log.SetFormatter(&log.JSONFormatter{})
103 // Output to stdout instead of the default stderr
104 // Can be any io.Writer, see below for File example
105 log.SetOutput(os.Stdout)
107 // Only log the warning severity or above.
108 log.SetLevel(log.WarnLevel)
112 log.WithFields(log.Fields{
115 }).Info("A group of walrus emerges from the ocean")
117 log.WithFields(log.Fields{
120 }).Warn("The group's number increased tremendously!")
122 log.WithFields(log.Fields{
125 }).Fatal("The ice breaks!")
127 // A common pattern is to re-use fields between logging statements by re-using
128 // the logrus.Entry returned from WithFields()
129 contextLogger := log.WithFields(log.Fields{
130 "common": "this is a common field",
131 "other": "I also should be logged always",
134 contextLogger.Info("I'll be logged with common and other field")
135 contextLogger.Info("Me too")
139 For more advanced usage such as logging to multiple locations from the same
140 application, you can also create an instance of the `logrus` Logger:
147 "github.com/sirupsen/logrus"
150 // Create a new instance of the logger. You can have any number of instances.
151 var log = logrus.New()
154 // The API for setting attributes is a little different than the package level
155 // exported logger. See Godoc.
158 // You could set this to any `io.Writer` such as a file
159 // file, err := os.OpenFile("logrus.log", os.O_CREATE|os.O_WRONLY, 0666)
163 // log.Info("Failed to log to file, using default stderr")
166 log.WithFields(logrus.Fields{
169 }).Info("A group of walrus emerges from the ocean")
175 Logrus encourages careful, structured logging through logging fields instead of
176 long, unparseable error messages. For example, instead of: `log.Fatalf("Failed
177 to send event %s to topic %s with key %d")`, you should log the much more
181 log.WithFields(log.Fields{
185 }).Fatal("Failed to send event")
188 We've found this API forces you to think about logging in a way that produces
189 much more useful logging messages. We've been in countless situations where just
190 a single added field to a log statement that was already there would've saved us
191 hours. The `WithFields` call is optional.
193 In general, with Logrus using any of the `printf`-family functions should be
194 seen as a hint you should add a field, however, you can still use the
195 `printf`-family functions with Logrus.
199 Often it's helpful to have fields _always_ attached to log statements in an
200 application or parts of one. For example, you may want to always log the
201 `request_id` and `user_ip` in the context of a request. Instead of writing
202 `log.WithFields(log.Fields{"request_id": request_id, "user_ip": user_ip})` on
203 every line, you can create a `logrus.Entry` to pass around instead:
206 requestLogger := log.WithFields(log.Fields{"request_id": request_id, "user_ip": user_ip})
207 requestLogger.Info("something happened on that request") # will log request_id and user_ip
208 requestLogger.Warn("something not great happened")
213 You can add hooks for logging levels. For example to send errors to an exception
214 tracking service on `Error`, `Fatal` and `Panic`, info to StatsD or log to
215 multiple places simultaneously, e.g. syslog.
217 Logrus comes with [built-in hooks](hooks/). Add those, or your custom hook, in
222 log "github.com/sirupsen/logrus"
223 "gopkg.in/gemnasium/logrus-airbrake-hook.v2" // the package is named "aibrake"
224 logrus_syslog "github.com/sirupsen/logrus/hooks/syslog"
230 // Use the Airbrake hook to report errors that have Error severity or above to
231 // an exception tracker. You can create custom hooks, see the Hooks section.
232 log.AddHook(airbrake.NewHook(123, "xyz", "production"))
234 hook, err := logrus_syslog.NewSyslogHook("udp", "localhost:514", syslog.LOG_INFO, "")
236 log.Error("Unable to connect to local syslog daemon")
242 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).
244 | Hook | Description |
245 | ----- | ----------- |
246 | [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. |
247 | [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. |
248 | [Amazon Kinesis](https://github.com/evalphobia/logrus_kinesis) | Hook for logging to [Amazon Kinesis](https://aws.amazon.com/kinesis/) |
249 | [Amqp-Hook](https://github.com/vladoatanasov/logrus_amqp) | Hook for logging to Amqp broker (Like RabbitMQ) |
250 | [AzureTableHook](https://github.com/kpfaulkner/azuretablehook/) | Hook for logging to Azure Table Storage|
251 | [Bugsnag](https://github.com/Shopify/logrus-bugsnag/blob/master/bugsnag.go) | Send errors to the Bugsnag exception tracking service. |
252 | [DeferPanic](https://github.com/deferpanic/dp-logrus) | Hook for logging to DeferPanic |
253 | [Discordrus](https://github.com/kz/discordrus) | Hook for logging to [Discord](https://discordapp.com/) |
254 | [ElasticSearch](https://github.com/sohlich/elogrus) | Hook for logging to ElasticSearch|
255 | [Firehose](https://github.com/beaubrewer/logrus_firehose) | Hook for logging to [Amazon Firehose](https://aws.amazon.com/kinesis/firehose/)
256 | [Fluentd](https://github.com/evalphobia/logrus_fluent) | Hook for logging to fluentd |
257 | [Go-Slack](https://github.com/multiplay/go-slack) | Hook for logging to [Slack](https://slack.com) |
258 | [Graylog](https://github.com/gemnasium/logrus-graylog-hook) | Hook for logging to [Graylog](http://graylog2.org/) |
259 | [Hiprus](https://github.com/nubo/hiprus) | Send errors to a channel in hipchat. |
260 | [Honeybadger](https://github.com/agonzalezro/logrus_honeybadger) | Hook for sending exceptions to Honeybadger |
261 | [InfluxDB](https://github.com/Abramovic/logrus_influxdb) | Hook for logging to influxdb |
262 | [Influxus](http://github.com/vlad-doru/influxus) | Hook for concurrently logging to [InfluxDB](http://influxdata.com/) |
263 | [Journalhook](https://github.com/wercker/journalhook) | Hook for logging to `systemd-journald` |
264 | [KafkaLogrus](https://github.com/tracer0tong/kafkalogrus) | Hook for logging to Kafka |
265 | [LFShook](https://github.com/rifflock/lfshook) | Hook for logging to the local filesystem |
266 | [Logentries](https://github.com/jcftang/logentriesrus) | Hook for logging to [Logentries](https://logentries.com/) |
267 | [Logentrus](https://github.com/puddingfactory/logentrus) | Hook for logging to [Logentries](https://logentries.com/) |
268 | [Logmatic.io](https://github.com/logmatic/logmatic-go) | Hook for logging to [Logmatic.io](http://logmatic.io/) |
269 | [Logrusly](https://github.com/sebest/logrusly) | Send logs to [Loggly](https://www.loggly.com/) |
270 | [Logstash](https://github.com/bshuster-repo/logrus-logstash-hook) | Hook for logging to [Logstash](https://www.elastic.co/products/logstash) |
271 | [Mail](https://github.com/zbindenren/logrus_mail) | Hook for sending exceptions via mail |
272 | [Mattermost](https://github.com/shuLhan/mattermost-integration/tree/master/hooks/logrus) | Hook for logging to [Mattermost](https://mattermost.com/) |
273 | [Mongodb](https://github.com/weekface/mgorus) | Hook for logging to mongodb |
274 | [NATS-Hook](https://github.com/rybit/nats_logrus_hook) | Hook for logging to [NATS](https://nats.io) |
275 | [Octokit](https://github.com/dorajistyle/logrus-octokit-hook) | Hook for logging to github via octokit |
276 | [Papertrail](https://github.com/polds/logrus-papertrail-hook) | Send errors to the [Papertrail](https://papertrailapp.com) hosted logging service via UDP. |
277 | [PostgreSQL](https://github.com/gemnasium/logrus-postgresql-hook) | Send logs to [PostgreSQL](http://postgresql.org) |
278 | [Pushover](https://github.com/toorop/logrus_pushover) | Send error via [Pushover](https://pushover.net) |
279 | [Raygun](https://github.com/squirkle/logrus-raygun-hook) | Hook for logging to [Raygun.io](http://raygun.io/) |
280 | [Redis-Hook](https://github.com/rogierlommers/logrus-redis-hook) | Hook for logging to a ELK stack (through Redis) |
281 | [Rollrus](https://github.com/heroku/rollrus) | Hook for sending errors to rollbar |
282 | [Scribe](https://github.com/sagar8192/logrus-scribe-hook) | Hook for logging to [Scribe](https://github.com/facebookarchive/scribe)|
283 | [Sentry](https://github.com/evalphobia/logrus_sentry) | Send errors to the Sentry error logging and aggregation service. |
284 | [Slackrus](https://github.com/johntdyer/slackrus) | Hook for Slack chat. |
285 | [Stackdriver](https://github.com/knq/sdhook) | Hook for logging to [Google Stackdriver](https://cloud.google.com/logging/) |
286 | [Sumorus](https://github.com/doublefree/sumorus) | Hook for logging to [SumoLogic](https://www.sumologic.com/)|
287 | [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. |
288 | [Syslog TLS](https://github.com/shinji62/logrus-syslog-ng) | Send errors to remote syslog server with TLS support. |
289 | [Telegram](https://github.com/rossmcdonald/telegram_hook) | Hook for logging errors to [Telegram](https://telegram.org/) |
290 | [TraceView](https://github.com/evalphobia/logrus_appneta) | Hook for logging to [AppNeta TraceView](https://www.appneta.com/products/traceview/) |
291 | [Typetalk](https://github.com/dragon3/logrus-typetalk-hook) | Hook for logging to [Typetalk](https://www.typetalk.in/) |
292 | [logz.io](https://github.com/ripcurld00d/logrus-logzio-hook) | Hook for logging to [logz.io](https://logz.io), a Log as a Service using Logstash |
293 | [SQS-Hook](https://github.com/tsarpaul/logrus_sqs) | Hook for logging to [Amazon Simple Queue Service (SQS)](https://aws.amazon.com/sqs/) |
297 Logrus has six logging levels: Debug, Info, Warning, Error, Fatal and Panic.
300 log.Debug("Useful debugging information.")
301 log.Info("Something noteworthy happened!")
302 log.Warn("You should probably take a look at this.")
303 log.Error("Something failed but I'm not quitting.")
304 // Calls os.Exit(1) after logging
306 // Calls panic() after logging
307 log.Panic("I'm bailing.")
310 You can set the logging level on a `Logger`, then it will only log entries with
311 that severity or anything above it:
314 // Will log anything that is info or above (warn, error, fatal, panic). Default.
315 log.SetLevel(log.InfoLevel)
318 It may be useful to set `log.Level = logrus.DebugLevel` in a debug or verbose
319 environment if your application has that.
323 Besides the fields added with `WithField` or `WithFields` some fields are
324 automatically added to all logging events:
326 1. `time`. The timestamp when the entry was created.
327 2. `msg`. The logging message passed to `{Info,Warn,Error,Fatal,Panic}` after
328 the `AddFields` call. E.g. `Failed to send event.`
329 3. `level`. The logging level. E.g. `info`.
333 Logrus has no notion of environment.
335 If you wish for hooks and formatters to only be used in specific environments,
336 you should handle that yourself. For example, if your application has a global
337 variable `Environment`, which is a string representation of the environment you
342 log "github.com/sirupsen/logrus"
346 // do something here to set environment depending on an environment variable
347 // or command-line flag
348 if Environment == "production" {
349 log.SetFormatter(&log.JSONFormatter{})
351 // The TextFormatter is default, you don't actually have to do this.
352 log.SetFormatter(&log.TextFormatter{})
357 This configuration is how `logrus` was intended to be used, but JSON in
358 production is mostly only useful if you do log aggregation with tools like
363 The built-in logging formatters are:
365 * `logrus.TextFormatter`. Logs the event in colors if stdout is a tty, otherwise
367 * *Note:* to force colored output when there is no TTY, set the `ForceColors`
368 field to `true`. To force no colored output even if there is a TTY set the
369 `DisableColors` field to `true`. For Windows, see
370 [github.com/mattn/go-colorable](https://github.com/mattn/go-colorable).
371 * All options are listed in the [generated docs](https://godoc.org/github.com/sirupsen/logrus#TextFormatter).
372 * `logrus.JSONFormatter`. Logs fields as JSON.
373 * All options are listed in the [generated docs](https://godoc.org/github.com/sirupsen/logrus#JSONFormatter).
375 Third party logging formatters:
377 * [`FluentdFormatter`](https://github.com/joonix/log). Formats entries that can by parsed by Kubernetes and Google Container Engine.
378 * [`logstash`](https://github.com/bshuster-repo/logrus-logstash-hook). Logs fields as [Logstash](http://logstash.net) Events.
379 * [`prefixed`](https://github.com/x-cray/logrus-prefixed-formatter). Displays log entry source along with alternative layout.
380 * [`zalgo`](https://github.com/aybabtme/logzalgo). Invoking the P͉̫o̳̼̊w̖͈̰͎e̬͔̭͂r͚̼̹̲ ̫͓͉̳͈ō̠͕͖̚f̝͍̠ ͕̲̞͖͑Z̖̫̤̫ͪa͉̬͈̗l͖͎g̳̥o̰̥̅!̣͔̲̻͊̄ ̙̘̦̹̦.
382 You can define your formatter by implementing the `Formatter` interface,
383 requiring a `Format` method. `Format` takes an `*Entry`. `entry.Data` is a
384 `Fields` type (`map[string]interface{}`) with all your fields as well as the
385 default ones (see Entries section above):
388 type MyJSONFormatter struct {
391 log.SetFormatter(new(MyJSONFormatter))
393 func (f *MyJSONFormatter) Format(entry *Entry) ([]byte, error) {
394 // Note this doesn't include Time, Level and Message which are available on
395 // the Entry. Consult `godoc` on information about those fields or read the
396 // source of the official loggers.
397 serialized, err := json.Marshal(entry.Data)
399 return nil, fmt.Errorf("Failed to marshal fields to JSON, %v", err)
401 return append(serialized, '\n'), nil
405 #### Logger as an `io.Writer`
407 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.
414 // create a stdlib log.Logger that writes to
416 ErrorLog: log.New(w, "", 0),
420 Each line written to that writer will be printed the usual way, using formatters
421 and hooks. The level for those entries is `info`.
423 This means that we can override the standard library logger easily:
426 logger := logrus.New()
427 logger.Formatter = &logrus.JSONFormatter{}
429 // Use logrus for standard log output
430 // Note that `log` here references stdlib's log
431 // Not logrus imported under the name `log`.
432 log.SetOutput(logger.Writer())
437 Log rotation is not provided with Logrus. Log rotation should be done by an
438 external program (like `logrotate(8)`) that can compress and delete old log
439 entries. It should not be a feature of the application-level logger.
443 | Tool | Description |
444 | ---- | ----------- |
445 |[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.|
446 |[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) |
450 Logrus has a built in facility for asserting the presence of log messages. This is implemented through the `test` hook and provides:
452 * decorators for existing logger (`test.NewLocal` and `test.NewGlobal`) which basically just add the `test` hook
453 * a test logger (`test.NewNullLogger`) that just records log messages (and does not output any):
457 "github.com/sirupsen/logrus"
458 "github.com/sirupsen/logrus/hooks/test"
459 "github.com/stretchr/testify/assert"
463 func TestSomething(t*testing.T){
464 logger, hook := test.NewNullLogger()
465 logger.Error("Helloerror")
467 assert.Equal(t, 1, len(hook.Entries))
468 assert.Equal(t, logrus.ErrorLevel, hook.LastEntry().Level)
469 assert.Equal(t, "Helloerror", hook.LastEntry().Message)
472 assert.Nil(t, hook.LastEntry())
478 Logrus can register one or more functions that will be called when any `fatal`
479 level message is logged. The registered handlers will be executed before
480 logrus performs a `os.Exit(1)`. This behavior may be helpful if callers need
481 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.
486 // gracefully shutdown something...
488 logrus.RegisterExitHandler(handler)
494 By default Logger is protected by mutex for concurrent writes, this mutex is invoked when calling hooks and writing logs.
495 If you are sure such locking is not needed, you can call logger.SetNoLock() to disable the locking.
497 Situation when locking is not needed includes:
499 * You have no hooks registered, or hooks calling is already thread-safe.
501 * Writing to logger.Out is already thread-safe, for example:
503 1) logger.Out is protected by locks.
505 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)
507 (Refer to http://www.notthewizard.com/2014/06/17/are-files-appends-really-atomic/)