re
/
logrus
forked from mirror/logrus
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

README: rewrite

This commit is contained in:
Simon Eskildsen 2014-02-23 20:19:34 -05:00
parent 520486e244
commit b6f53cb91b
1 changed files with 58 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
README.md
View File

@ -1,67 +1,75 @@
# Logrus # Logrus
Logrus is a simple, opinionated logging package for Go. It has three debugging Logrus is a simple, opinionated logging package for Go. Features include:
levels:
* `LevelDebug`: Debugging, usually turned off for deploys. * **Level logging**. Logrus has the levels: Debug, Info, Warning and Fatal.
* `LevelInfo`: Info, useful for monitoring in production. * **Exceptions**. Warnings will log as an exception along with logging it to
* `LevelWarning`: Warnings that should definitely be noted. These are sent to out, without quitting. Fatal will do the same, but call `os.Exit(1)` after
`airbrake`. emitting the exception.
* `LevelFatal`: Fatal messages that causes the application to crash. These are * **JSON**. Logrus currently logs as JSON by default.
sent to `airbrake`.
## Usage The API is completely compatible with the Go standard lib logger, with only the
features above added.
The global logging level is set by: `logrus.Level = logrus.{LevelDebug,LevelWarning,LevelFatal}`. ## Motivation
Note that for `airbrake` to work, `airbrake.Endpoint` and `airbrake.ApiKey` The motivation for this library came out of a pattern seen in Go applications me
should be set. and others have been writing with functions such as:
There is a global logger, which new loggers inherit their settings from when
created (see example below), such as the place to redirect output. Logging can
be done with the global logging module:
```go ```go
logrus.Debug("Something debugworthy happened: %s", importantStuff) func reportFatalError(err error) {
logrus.Info("Something infoworthy happened: %s", importantStuff) airbrake.Notify(err)
log.Fatal(err)
}
logrus.Warning("Something bad happened: %s", importantStuff) func reportWarning(err error) {
// Reports to Airbrake airbrake.Notify(err)
}
logrus.Fatal("Something fatal happened: %s", importantStuff)
// Reports to Airbrake
// Then exits
``` ```
Types are encouraged to include their own logging object. This allows to set a JSON logging is excellent for parsing logs for analysis and troubleshooting.
context dependent prefix to know where a certain message is coming from, without It's supported natively by log aggregators such as logstash and Splunk. Logging
cluttering every single message with this. JSON with logrus with the `WithFields` and `WithField` API in logrus forces you
to think about what context to log, to provide valuable troubleshoot information
later.
## Example
```go ```go
type Walrus struct { import (
TuskSize uint64 "github.com/Sirupsen/logrus"
Sex bool )
logger logrus.Logger
}
func NewWalrus(tuskSize uint64, sex bool) *Walrus { var logger logrus.New()
return &Walrus{ func main() {
TuskSize: tuskSize, logger.WithFields(Fields{
Sex: bool, "animal": "walrus",
logger: logrus.NewLogger("Walrus"), "location": "New York Aquarium",
} "weather": "rain",
} "name": "Wally",
"event": "escape",
}).Info("Walrus has escaped the aquarium! Action required!")
// {
// "level": "info",
// "animal": "walrus",
// "location": "New York Aquarium",
// "weather":"rain",
// "name": "Wally",
// "event":"escape",
// "msg": "Walrus has escaped the aquarium! Action required!")
// "time": "2014-02-23 19:57:35.862271048 -0500 EST"
// }
func (walrus *Walrus) Mate(partner *Walrus) error { logger.WithField("source", "kafka").Infof("Connection to Kafka failed with %s", "some error")
if walrus.Sex == partner.Sex { // {
return errors.New("Incompatible mating partner.") // "level": "info",
} // "source": "kafka",
// "msg": "Connection to Kafka failed with some error",
walrus.logger.Info("Walrus with tusk sizes %d and %d are mating!", walrus.TuskSize, partner.TuskSize) // "time": "2014-02-23 19:57:35.862271048 -0500 EST"
// Generates a logging message: <timestamp> [Info] [Walrus] Walrus with tusk sizes <int> and <int> are mating! // }
// Walrus mating happens here
return nil
} }
``` ```
Using `Warning` and `Fatal` to log to `airbrake` requires setting
`airbrake.Endpoint` and `airbrake.ApiKey`. See
[tobi/airbrake-go](https://github.com/tobi/airbrake-go).