forked from mirror/logrus
450 lines
18 KiB
Markdown
450 lines
18 KiB
Markdown
# Logrus <img src="http://i.imgur.com/hTeVwmJ.png" width="40" height="40" alt=":walrus:" class="emoji" title=":walrus:"/> [](https://travis-ci.org/Sirupsen/logrus) [](https://godoc.org/github.com/Sirupsen/logrus)
|
|
|
|
Logrus is a structured logger for Go (golang), completely API compatible with
|
|
the standard library logger. [Godoc][godoc]. **Please note the Logrus API is not
|
|
yet stable (pre 1.0). Logrus itself is completely stable and has been used in
|
|
many large deployments. The core API is unlikely to change much but please
|
|
version control your Logrus to make sure you aren't fetching latest `master` on
|
|
every build.**
|
|
|
|
Nicely color-coded in development (when a TTY is attached, otherwise just
|
|
plain text):
|
|
|
|
|
|
|
|
With `log.SetFormatter(&log.JSONFormatter{})`, for easy parsing by logstash
|
|
or Splunk:
|
|
|
|
```json
|
|
{"animal":"walrus","level":"info","msg":"A group of walrus emerges from the
|
|
ocean","size":10,"time":"2014-03-10 19:57:38.562264131 -0400 EDT"}
|
|
|
|
{"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!",
|
|
"size":10,"time":"2014-03-10 19:57:38.562500591 -0400 EDT"}
|
|
|
|
{"animal":"walrus","level":"info","msg":"Tremendously sized cow enters the ocean.",
|
|
"size":9,"time":"2014-03-10 19:57:38.562527896 -0400 EDT"}
|
|
|
|
{"level":"fatal","msg":"The ice breaks!","number":100,"omg":true,
|
|
"time":"2014-03-10 19:57:38.562543128 -0400 EDT"}
|
|
```
|
|
|
|
With the default `log.SetFormatter(&log.TextFormatter{})` when a TTY is not
|
|
attached, the output is compatible with the
|
|
[logfmt](http://godoc.org/github.com/kr/logfmt) format:
|
|
|
|
```text
|
|
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
|
|
```
|
|
To ensure this behaviour even if a TTY is attached, set your formatter as follows:
|
|
|
|
```
|
|
log.SetFormatter(&log.TextFormatter{
|
|
DisableColors: true,
|
|
FullTimestamp: true,
|
|
})
|
|
```
|
|
|
|
If you wish to add the calling method as a field, instruct the logger via:
|
|
```
|
|
log.SetReportMethod(true)
|
|
```
|
|
This adds the caller as 'method' like so:
|
|
|
|
```json
|
|
{"animal":"penguin","level":"fatal","method":"arcticcreatures.migrate","msg":"a penguin swims by",
|
|
"time":"2014-03-10 19:57:38.562543129 -0400 EDT"}
|
|
|
|
```
|
|
|
|
```text
|
|
time="2015-03-26T01:27:38-04:00" level=fatal method=arcticcreatures.migrate msg="a penguin swims by" animal=penguin
|
|
|
|
```
|
|
#### Example
|
|
|
|
The simplest way to use Logrus is simply the package-level exported logger:
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
log "github.com/Sirupsen/logrus"
|
|
)
|
|
|
|
func main() {
|
|
log.WithFields(log.Fields{
|
|
"animal": "walrus",
|
|
}).Info("A walrus appears")
|
|
}
|
|
```
|
|
|
|
Note that it's completely api-compatible with the stdlib logger, so you can
|
|
replace your `log` imports everywhere with `log "github.com/Sirupsen/logrus"`
|
|
and you'll now have the flexibility of Logrus. You can customize it all you
|
|
want:
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"os"
|
|
log "github.com/Sirupsen/logrus"
|
|
)
|
|
|
|
func init() {
|
|
// Log as JSON instead of the default ASCII formatter.
|
|
log.SetFormatter(&log.JSONFormatter{})
|
|
|
|
// Output to stderr instead of stdout, could also be a file.
|
|
log.SetOutput(os.Stderr)
|
|
|
|
// Only log the warning severity or above.
|
|
log.SetLevel(log.WarnLevel)
|
|
}
|
|
|
|
func main() {
|
|
log.WithFields(log.Fields{
|
|
"animal": "walrus",
|
|
"size": 10,
|
|
}).Info("A group of walrus emerges from the ocean")
|
|
|
|
log.WithFields(log.Fields{
|
|
"omg": true,
|
|
"number": 122,
|
|
}).Warn("The group's number increased tremendously!")
|
|
|
|
log.WithFields(log.Fields{
|
|
"omg": true,
|
|
"number": 100,
|
|
}).Fatal("The ice breaks!")
|
|
|
|
// A common pattern is to re-use fields between logging statements by re-using
|
|
// the logrus.Entry returned from WithFields()
|
|
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")
|
|
}
|
|
```
|
|
|
|
For more advanced usage such as logging to multiple locations from the same
|
|
application, you can also create an instance of the `logrus` Logger:
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"github.com/Sirupsen/logrus"
|
|
)
|
|
|
|
// 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.
|
|
log.Out = os.Stderr
|
|
|
|
log.WithFields(logrus.Fields{
|
|
"animal": "walrus",
|
|
"size": 10,
|
|
}).Info("A group of walrus emerges from the ocean")
|
|
}
|
|
```
|
|
|
|
#### Fields
|
|
|
|
Logrus encourages careful, structured logging though logging fields instead of
|
|
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:
|
|
|
|
```go
|
|
log.WithFields(log.Fields{
|
|
"event": event,
|
|
"topic": topic,
|
|
"key": key,
|
|
}).Fatal("Failed to send event")
|
|
```
|
|
|
|
We've found this API forces you to think about logging in a way that produces
|
|
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.
|
|
|
|
In general, with Logrus using any of the `printf`-family functions should be
|
|
seen as a hint you should add a field, however, you can still use the
|
|
`printf`-family functions with Logrus.
|
|
|
|
#### Hooks
|
|
|
|
You can add hooks for logging levels. For example to send errors to an exception
|
|
tracking service on `Error`, `Fatal` and `Panic`, info to StatsD or log to
|
|
multiple places simultaneously, e.g. syslog.
|
|
|
|
Logrus comes with [built-in hooks](hooks/). Add those, or your custom hook, in
|
|
`init`:
|
|
|
|
```go
|
|
import (
|
|
log "github.com/Sirupsen/logrus"
|
|
"gopkg.in/gemnasium/logrus-airbrake-hook.v2" // the package is named "aibrake"
|
|
logrus_syslog "github.com/Sirupsen/logrus/hooks/syslog"
|
|
"log/syslog"
|
|
)
|
|
|
|
func init() {
|
|
|
|
// 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"))
|
|
|
|
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)
|
|
}
|
|
}
|
|
```
|
|
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).
|
|
|
|
| Hook | Description |
|
|
| ----- | ----------- |
|
|
| [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. |
|
|
| [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. |
|
|
| [Papertrail](https://github.com/polds/logrus-papertrail-hook) | Send errors to the [Papertrail](https://papertrailapp.com) hosted logging service via UDP. |
|
|
| [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. |
|
|
| [Bugsnag](https://github.com/Shopify/logrus-bugsnag/blob/master/bugsnag.go) | Send errors to the Bugsnag exception tracking service. |
|
|
| [Sentry](https://github.com/evalphobia/logrus_sentry) | Send errors to the Sentry error logging and aggregation service. |
|
|
| [Hiprus](https://github.com/nubo/hiprus) | Send errors to a channel in hipchat. |
|
|
| [Logrusly](https://github.com/sebest/logrusly) | Send logs to [Loggly](https://www.loggly.com/) |
|
|
| [Slackrus](https://github.com/johntdyer/slackrus) | Hook for Slack chat. |
|
|
| [Journalhook](https://github.com/wercker/journalhook) | Hook for logging to `systemd-journald` |
|
|
| [Graylog](https://github.com/gemnasium/logrus-graylog-hook) | Hook for logging to [Graylog](http://graylog2.org/) |
|
|
| [Raygun](https://github.com/squirkle/logrus-raygun-hook) | Hook for logging to [Raygun.io](http://raygun.io/) |
|
|
| [LFShook](https://github.com/rifflock/lfshook) | Hook for logging to the local filesystem |
|
|
| [Honeybadger](https://github.com/agonzalezro/logrus_honeybadger) | Hook for sending exceptions to Honeybadger |
|
|
| [Mail](https://github.com/zbindenren/logrus_mail) | Hook for sending exceptions via mail |
|
|
| [Rollrus](https://github.com/heroku/rollrus) | Hook for sending errors to rollbar |
|
|
| [Fluentd](https://github.com/evalphobia/logrus_fluent) | Hook for logging to fluentd |
|
|
| [Mongodb](https://github.com/weekface/mgorus) | Hook for logging to mongodb |
|
|
| [Influxus] (http://github.com/vlad-doru/influxus) | Hook for concurrently logging to [InfluxDB] (http://influxdata.com/) |
|
|
| [InfluxDB](https://github.com/Abramovic/logrus_influxdb) | Hook for logging to influxdb |
|
|
| [Octokit](https://github.com/dorajistyle/logrus-octokit-hook) | Hook for logging to github via octokit |
|
|
| [DeferPanic](https://github.com/deferpanic/dp-logrus) | Hook for logging to DeferPanic |
|
|
| [Redis-Hook](https://github.com/rogierlommers/logrus-redis-hook) | Hook for logging to a ELK stack (through Redis) |
|
|
| [Amqp-Hook](https://github.com/vladoatanasov/logrus_amqp) | Hook for logging to Amqp broker (Like RabbitMQ) |
|
|
| [KafkaLogrus](https://github.com/goibibo/KafkaLogrus) | Hook for logging to kafka |
|
|
| [Typetalk](https://github.com/dragon3/logrus-typetalk-hook) | Hook for logging to [Typetalk](https://www.typetalk.in/) |
|
|
| [ElasticSearch](https://github.com/sohlich/elogrus) | Hook for logging to ElasticSearch|
|
|
| [Sumorus](https://github.com/doublefree/sumorus) | Hook for logging to [SumoLogic](https://www.sumologic.com/)|
|
|
| [Scribe](https://github.com/sagar8192/logrus-scribe-hook) | Hook for logging to [Scribe](https://github.com/facebookarchive/scribe)|
|
|
| [Logstash](https://github.com/bshuster-repo/logrus-logstash-hook) | Hook for logging to [Logstash](https://www.elastic.co/products/logstash) |
|
|
| [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 |
|
|
| [Logmatic.io](https://github.com/logmatic/logmatic-go) | Hook for logging to [Logmatic.io](http://logmatic.io/) |
|
|
| [Pushover](https://github.com/toorop/logrus_pushover) | Send error via [Pushover](https://pushover.net) |
|
|
| [PostgreSQL](https://github.com/gemnasium/logrus-postgresql-hook) | Send logs to [PostgreSQL](http://postgresql.org) |
|
|
|
|
|
|
#### Level logging
|
|
|
|
Logrus has six logging levels: Debug, Info, Warning, Error, Fatal and Panic.
|
|
|
|
```go
|
|
log.Debug("Useful debugging information.")
|
|
log.Info("Something noteworthy happened!")
|
|
log.Warn("You should probably take a look at this.")
|
|
log.Error("Something failed but I'm not quitting.")
|
|
// Calls os.Exit(1) after logging
|
|
log.Fatal("Bye.")
|
|
// Calls panic() after logging
|
|
log.Panic("I'm bailing.")
|
|
```
|
|
|
|
You can set the logging level on a `Logger`, then it will only log entries with
|
|
that severity or anything above it:
|
|
|
|
```go
|
|
// Will log anything that is info or above (warn, error, fatal, panic). Default.
|
|
log.SetLevel(log.InfoLevel)
|
|
```
|
|
|
|
It may be useful to set `log.Level = logrus.DebugLevel` in a debug or verbose
|
|
environment if your application has that.
|
|
|
|
#### 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
|
|
|
|
Logrus has no notion of environment.
|
|
|
|
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:
|
|
|
|
```go
|
|
import (
|
|
log "github.com/Sirupsen/logrus"
|
|
)
|
|
|
|
init() {
|
|
// do something here to set environment depending on an environment variable
|
|
// or command-line flag
|
|
if Environment == "production" {
|
|
log.SetFormatter(&log.JSONFormatter{})
|
|
} else {
|
|
// The TextFormatter is default, you don't actually have to do this.
|
|
log.SetFormatter(&log.TextFormatter{})
|
|
}
|
|
}
|
|
```
|
|
|
|
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
|
|
|
|
The built-in logging formatters are:
|
|
|
|
* `logrus.TextFormatter`. Logs the event in colors if stdout is a tty, otherwise
|
|
without colors.
|
|
* *Note:* to force colored output when there is no TTY, set the `ForceColors`
|
|
field to `true`. To force no colored output even if there is a TTY set the
|
|
`DisableColors` field to `true`
|
|
* `logrus.JSONFormatter`. Logs fields as JSON.
|
|
|
|
Third party logging formatters:
|
|
|
|
* [`logstash`](https://github.com/bshuster-repo/logrus-logstash-hook). Logs fields as [Logstash](http://logstash.net) Events.
|
|
* [`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̰̥̅!̣͔̲̻͊̄ ̙̘̦̹̦.
|
|
|
|
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):
|
|
|
|
```go
|
|
type MyJSONFormatter struct {
|
|
}
|
|
|
|
log.SetFormatter(new(MyJSONFormatter))
|
|
|
|
func (f *MyJSONFormatter) Format(entry *Entry) ([]byte, error) {
|
|
// 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.
|
|
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
|
|
}
|
|
```
|
|
|
|
#### Logger as an `io.Writer`
|
|
|
|
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.
|
|
|
|
```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`.
|
|
|
|
#### Rotation
|
|
|
|
Log rotation is not provided with Logrus. Log rotation should be done by an
|
|
external program (like `logrotate(8)`) that can compress and delete old log
|
|
entries. It should not be a feature of the application-level logger.
|
|
|
|
#### Tools
|
|
|
|
| Tool | Description |
|
|
| ---- | ----------- |
|
|
|[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.|
|
|
|[Logrus Viper Helper](https://github.com/heirko/go-contrib/tree/master/logrusHelper)|An Helper arround 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) |
|
|
|
|
#### 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
|
|
logger, hook := NewNullLogger()
|
|
logger.Error("Hello error")
|
|
|
|
assert.Equal(1, len(hook.Entries))
|
|
assert.Equal(logrus.ErrorLevel, hook.LastEntry().Level)
|
|
assert.Equal("Hello error", hook.LastEntry().Message)
|
|
|
|
hook.Reset()
|
|
assert.Nil(hook.LastEntry())
|
|
```
|
|
|
|
#### 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)
|
|
...
|
|
```
|
|
|
|
#### Thread safty
|
|
|
|
By default Logger is protected by mutex for concurrent writes, this mutex is invoked when calling hooks and writing logs.
|
|
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/)
|