logrus/README.md

270 lines
8.6 KiB
Markdown
Raw Normal View History

# Logrus <img src="http://i.imgur.com/hTeVwmJ.png" width="40" height="40" alt=":walrus:" class="emoji" title=":walrus:"/>&nbsp;[![Build Status](https://travis-ci.org/Sirupsen/logrus.svg?branch=master)](https://travis-ci.org/Sirupsen/logrus)
2013-10-16 23:27:10 +04:00
2014-03-11 04:07:22 +04:00
Logrus is a structured logger for Go (golang), completely API compatible with
2014-03-13 16:44:08 +04:00
the standard library logger. [Godoc][godoc].
2013-10-16 23:27:10 +04:00
2014-03-11 04:00:07 +04:00
Nicely color-coded in development (when a TTY is attached, otherwise just
plain text):
2014-03-11 03:59:18 +04:00
2014-03-11 04:00:07 +04:00
![Colored](http://i.imgur.com/PY7qMwd.png)
2014-03-11 03:59:18 +04:00
2014-03-11 04:01:07 +04:00
With `log.Formatter = new(logrus.JSONFormatter)`, for easy parsing by logstash
or Splunk:
2014-03-11 03:59:18 +04:00
```json
{"animal":"walrus","level":"info","msg":"A group of walrus emerges from the
2014-03-15 00:17:18 +04:00
ocean","size":10,"time":"2014-03-10 19:57:38.562264131 -0400 EDT"}
2014-03-11 04:06:39 +04: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-15 00:17:18 +04:00
"size":10,"time":"2014-03-10 19:57:38.562500591 -0400 EDT"}
2014-03-11 04:06:39 +04:00
{"animal":"walrus","level":"info","msg":"Tremendously sized cow enters the ocean.",
2014-03-15 00:17:18 +04:00
"size":9,"time":"2014-03-10 19:57:38.562527896 -0400 EDT"}
2014-03-11 04:06:39 +04:00
{"level":"fatal","msg":"The ice breaks!","number":100,"omg":true,
"time":"2014-03-10 19:57:38.562543128 -0400 EDT"}
2014-03-11 03:59:18 +04:00
```
2014-04-24 04:21:38 +04:00
With the default `log.Formatter = new(logrus.TextFormatter)` when a TTY is not
attached, the output is compatible with the
[l2met](http://r.32k.io/l2met-introduction) format:
```text
time="2014-04-20 15:36:23.830442383 -0400 EDT" level="info" msg="A group of walrus emerges from the ocean" animal="walrus" size=10
time="2014-04-20 15:36:23.830584199 -0400 EDT" level="warning" msg="The group's number increased tremendously!" omg=true number=122
time="2014-04-20 15:36:23.830596521 -0400 EDT" level="info" msg="A giant walrus appears!" animal="walrus" size=10
time="2014-04-20 15:36:23.830611837 -0400 EDT" level="info" msg="Tremendously sized cow enters the ocean." animal="walrus" size=9
time="2014-04-20 15:36:23.830626464 -0400 EDT" level="fatal" msg="The ice breaks!" omg=true number=100
```
2014-04-14 01:51:46 +04:00
#### Example
2014-04-24 04:21:38 +04:00
Note again that Logrus is API compatible with the stdlib logger, so if you
2014-04-14 01:51:46 +04:00
remove the `log` import and create a global `log` variable as below it will just
work.
```go
package main
import (
"github.com/Sirupsen/logrus"
)
var log = logrus.New()
func init() {
log.Formatter = new(logrus.JSONFormatter)
log.Formatter = new(logrus.TextFormatter) // default
}
func main() {
log.WithFields(logrus.Fields{
"animal": "walrus",
"size": 10,
}).Info("A group of walrus emerges from the ocean")
log.WithFields(logrus.Fields{
"omg": true,
"number": 122,
}).Warn("The group's number increased tremendously!")
log.WithFields(logrus.Fields{
"omg": true,
"number": 100,
}).Fatal("The ice breaks!")
}
```
#### Package logging
Alike the stdlib logger, logrus exposes functions that you can use to log
to a default global logger. This is convenient to avoid passing a
`logrus.Logger` thorough your app's packages; you can simply setup `logrus
from your main package and use the package function directly accross your app.
2014-03-07 06:20:13 +04:00
#### Fields
2013-10-16 23:27:10 +04:00
2014-04-24 04:21:38 +04:00
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:
2013-10-16 23:27:10 +04:00
2014-03-07 06:20:13 +04:00
```go
log = logrus.New()
2014-03-11 03:27:19 +04:00
2014-03-11 07:23:53 +04:00
log.WithFields(logrus.Fields{
2014-03-07 06:20:13 +04:00
"event": event,
"topic": topic,
"key": key,
2014-03-07 06:20:13 +04: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 19:01:18 +04: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 06:20:13 +04:00
2014-03-07 06:26:05 +04:00
In general, with Logrus using any of the `printf`-family functions should be
2014-04-24 04:21:38 +04:00
seen as a hint you should add a field, however, you can still use the
2014-03-07 06:26:05 +04:00
`printf`-family functions with Logrus.
2014-03-07 06:20:13 +04:00
#### Hooks
2013-10-16 23:27:10 +04:00
2014-03-07 06:26:05 +04:00
You can add hooks for logging levels. For example to send errors to an exception
2014-04-24 04:21:38 +04:00
tracking service on `Error`, `Fatal` and `Panic`, info to StatsD or log to
multiple places simultaneously, e.g. syslog.
2013-10-16 23:27:10 +04:00
```go
2014-04-24 04:21:38 +04:00
// Not the real implementation of the Airbrake hook. Just a simple sample.
var log = logrus.New()
func init() {
log.Hooks.Add(new(AirbrakeHook))
}
2014-03-11 03:27:19 +04:00
2014-03-11 07:23:53 +04:00
type AirbrakeHook struct{}
2014-03-11 03:27:19 +04:00
2014-03-11 03:30:06 +04:00
// `Fire()` takes the entry that the hook is fired for. `entry.Data[]` contains
// the fields for the entry. See the Fields section of the README.
2014-03-11 07:23:53 +04:00
func (hook *AirbrakeHook) Fire(entry *logrus.Entry) error {
err := airbrake.Notify(entry.Data["error"].(error))
2014-03-07 06:20:13 +04:00
if err != nil {
log.WithFields(logrus.Fields{
2014-03-11 07:23:53 +04:00
"source": "airbrake",
2014-03-07 06:20:13 +04:00
"endpoint": airbrake.Endpoint,
}).Info("Failed to send error to Airbrake")
}
2014-03-11 03:27:19 +04:00
return nil
}
2014-03-11 03:52:39 +04:00
// `Levels()` returns a slice of `Levels` the hook is fired for.
func (hook *AirbrakeHook) Levels() []logrus.Level {
return []logrus.Level{
logrus.ErrorLevel,
logrus.FatalLevel,
logrus.PanicLevel,
2014-03-11 03:27:19 +04:00
}
}
2014-03-07 06:20:13 +04:00
```
Logrus comes with built-in hooks. Add those, or your custom hook, in `init`:
```go
import (
"github.com/Sirupsen/logrus"
"github.com/Sirupsen/logrus/hooks/airbrake"
)
func init() {
log.Hooks.Add(new(logrus_airbrake.AirbrakeHook))
}
```
* [`github.com/Sirupsen/logrus/hooks/airbrake`](https://github.com/Sirupsen/logrus/blob/master/hooks/airbrake/airbrake.go).
Send errors to an exception tracking service compatible with the Airbrake API.
Uses [`airbrake-go`](https://github.com/tobi/airbrake-go) behind the scenes.
2014-03-07 06:20:13 +04:00
#### Level logging
2013-10-16 23:27:10 +04:00
2014-03-11 04:06:39 +04:00
Logrus has six logging levels: Debug, Info, Warning, Error, Fatal and Panic.
2013-10-16 23:27:10 +04:00
2014-02-24 05:19:34 +04:00
```go
2014-03-07 06:49:10 +04:00
log.Debug("Useful debugging information.")
2014-03-07 06:20:13 +04: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 16:00:18 +04:00
// Calls os.Exit(1) after logging
2014-03-07 06:20:13 +04:00
log.Fatal("Bye.")
2014-03-12 16:00:18 +04:00
// Calls panic() after logging
2014-03-07 06:20:13 +04:00
log.Panic("I'm bailing.")
```
2014-03-11 04:06:39 +04: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 06:49:10 +04:00
```go
2014-03-11 04:06:39 +04:00
// Will log anything that is info or above (warn, error, fatal, panic). Default.
2014-03-11 03:52:39 +04:00
log.Level = logrus.Info
2014-03-07 06:49:10 +04:00
```
2014-03-11 04:06:39 +04:00
It may be useful to set `log.Level = logrus.Debug` in a debug or verbose
environment if your application has that.
2014-03-07 06:20:13 +04: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 23:21:54 +04:00
Logrus has no notion of environment.
2014-03-11 04:06:39 +04: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 06:20:13 +04:00
```go
init() {
// do something here to set environment depending on an environment variable
// or command-line flag
2014-03-11 03:27:19 +04:00
log := logrus.New()
2014-03-07 06:20:13 +04:00
if Environment == "production" {
2014-03-11 03:27:19 +04:00
log.Formatter = new(logrus.JSONFormatter)
2014-03-07 06:20:13 +04:00
} else {
// The TextFormatter is default, you don't actually have to do this.
2014-03-11 03:27:19 +04:00
log.Formatter = new(logrus.TextFormatter)
2014-03-07 06:20:13 +04:00
}
2013-10-16 23:27:10 +04:00
}
```
2014-02-24 05:19:34 +04:00
2014-03-11 04:06:39 +04: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 06:20:13 +04:00
2014-03-14 23:21:54 +04:00
The built-in logging formatters are:
2014-03-07 06:20:13 +04:00
* `logrus.TextFormatter`. Logs the event in colors if stdout is a tty, otherwise
2014-03-07 21:51:29 +04:00
without colors.
* *Note:* to force colored output when there is no TTY, set the `ForceColors`
field to `true`.
2014-03-07 21:51:29 +04:00
* `logrus.JSONFormatter`. Logs fields as JSON.
2014-03-07 06:20:13 +04:00
2014-03-14 23:21:54 +04:00
Third party logging formatters:
* [`zalgo`](https://github.com/aybabtme/logzalgo): invoking the P͉̫o̳̼̊w̖͈̰͎e̬͔̭͂r͚̼̹̲ ̫͓͉̳͈ō̠͕͖̚f̝͍̠ ͕̲̞͖͑Z̖̫̤̫ͪa͉̬͈̗l͖͎g̳̥o̰̥̅!̣͔̲̻͊̄ ̙̘̦̹̦.
2014-03-14 23:21:54 +04:00
2014-03-11 04:06:39 +04: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 06:20:13 +04:00
```go
2014-03-11 03:27:19 +04:00
type MyJSONFormatter struct {
}
log.Formatter = new(MyJSONFormatter)
func (f *JSONFormatter) Format(entry *Entry) ([]byte, error) {
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 06:20:13 +04:00
```
2014-03-11 05:15:25 +04:00
2014-03-13 16:44:08 +04:00
[godoc]: https://godoc.org/github.com/Sirupsen/logrus