forked from lug/matterbridge
149 lines
4.3 KiB
Markdown
149 lines
4.3 KiB
Markdown
jWalterWeatherman
|
||
=================
|
||
|
||
Seamless printing to the terminal (stdout) and logging to a io.Writer
|
||
(file) that’s as easy to use as fmt.Println.
|
||
|
||
|
||
Graphic by [JonnyEtc](http://jonnyetc.deviantart.com/art/And-That-s-Why-You-Always-Leave-a-Note-315311422)
|
||
|
||
JWW is primarily a wrapper around the excellent standard log library. It
|
||
provides a few advantages over using the standard log library alone.
|
||
|
||
1. Ready to go out of the box.
|
||
2. One library for both printing to the terminal and logging (to files).
|
||
3. Really easy to log to either a temp file or a file you specify.
|
||
|
||
|
||
I really wanted a very straightforward library that could seamlessly do
|
||
the following things.
|
||
|
||
1. Replace all the println, printf, etc statements thoughout my code with
|
||
something more useful
|
||
2. Allow the user to easily control what levels are printed to stdout
|
||
3. Allow the user to easily control what levels are logged
|
||
4. Provide an easy mechanism (like fmt.Println) to print info to the user
|
||
which can be easily logged as well
|
||
5. Due to 2 & 3 provide easy verbose mode for output and logs
|
||
6. Not have any unnecessary initialization cruft. Just use it.
|
||
|
||
# Usage
|
||
|
||
## Step 1. Use it
|
||
Put calls throughout your source based on type of feedback.
|
||
No initialization or setup needs to happen. Just start calling things.
|
||
|
||
Available Loggers are:
|
||
|
||
* TRACE
|
||
* DEBUG
|
||
* INFO
|
||
* WARN
|
||
* ERROR
|
||
* CRITICAL
|
||
* FATAL
|
||
|
||
These each are loggers based on the log standard library and follow the
|
||
standard usage. Eg.
|
||
|
||
```go
|
||
import (
|
||
jww "github.com/spf13/jwalterweatherman"
|
||
)
|
||
|
||
...
|
||
|
||
if err != nil {
|
||
|
||
// This is a pretty serious error and the user should know about
|
||
// it. It will be printed to the terminal as well as logged under the
|
||
// default thresholds.
|
||
|
||
jww.ERROR.Println(err)
|
||
}
|
||
|
||
if err2 != nil {
|
||
// This error isn’t going to materially change the behavior of the
|
||
// application, but it’s something that may not be what the user
|
||
// expects. Under the default thresholds, Warn will be logged, but
|
||
// not printed to the terminal.
|
||
|
||
jww.WARN.Println(err2)
|
||
}
|
||
|
||
// Information that’s relevant to what’s happening, but not very
|
||
// important for the user. Under the default thresholds this will be
|
||
// discarded.
|
||
|
||
jww.INFO.Printf("information %q", response)
|
||
|
||
```
|
||
|
||
NOTE: You can also use the library in a non-global setting by creating an instance of a Notebook:
|
||
|
||
```go
|
||
notepad = jww.NewNotepad(jww.LevelInfo, jww.LevelTrace, os.Stdout, ioutil.Discard, "", log.Ldate|log.Ltime)
|
||
notepad.WARN.Println("Some warning"")
|
||
```
|
||
|
||
_Why 7 levels?_
|
||
|
||
Maybe you think that 7 levels are too much for any application... and you
|
||
are probably correct. Just because there are seven levels doesn’t mean
|
||
that you should be using all 7 levels. Pick the right set for your needs.
|
||
Remember they only have to mean something to your project.
|
||
|
||
## Step 2. Optionally configure JWW
|
||
|
||
Under the default thresholds :
|
||
|
||
* Debug, Trace & Info goto /dev/null
|
||
* Warn and above is logged (when a log file/io.Writer is provided)
|
||
* Error and above is printed to the terminal (stdout)
|
||
|
||
### Changing the thresholds
|
||
|
||
The threshold can be changed at any time, but will only affect calls that
|
||
execute after the change was made.
|
||
|
||
This is very useful if your application has a verbose mode. Of course you
|
||
can decide what verbose means to you or even have multiple levels of
|
||
verbosity.
|
||
|
||
|
||
```go
|
||
import (
|
||
jww "github.com/spf13/jwalterweatherman"
|
||
)
|
||
|
||
if Verbose {
|
||
jww.SetLogThreshold(jww.LevelTrace)
|
||
jww.SetStdoutThreshold(jww.LevelInfo)
|
||
}
|
||
```
|
||
|
||
Note that JWW's own internal output uses log levels as well, so set the log
|
||
level before making any other calls if you want to see what it's up to.
|
||
|
||
|
||
### Setting a log file
|
||
|
||
JWW can log to any `io.Writer`:
|
||
|
||
|
||
```go
|
||
|
||
jww.SetLogOutput(customWriter)
|
||
|
||
```
|
||
|
||
|
||
# More information
|
||
|
||
This is an early release. I’ve been using it for a while and this is the
|
||
third interface I’ve tried. I like this one pretty well, but no guarantees
|
||
that it won’t change a bit.
|
||
|
||
I wrote this for use in [hugo](https://gohugo.io). If you are looking
|
||
for a static website engine that’s super fast please checkout Hugo.
|