jwalterweatherman

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2019 License: MIT Imports: 6 Imported by: 0

README

jWalterWeatherman

Seamless printing to the terminal (stdout) and logging to a io.Writer (file) that’s as easy to use as fmt.Println.

and_that__s_why_you_always_leave_a_note_by_jonnyetc-d57q7um Graphic by JonnyEtc

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.

    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:

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.

    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:


    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. If you are looking for a static website engine that’s super fast please checkout Hugo.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	TRACE    *log.Logger
	DEBUG    *log.Logger
	INFO     *log.Logger
	WARN     *log.Logger
	ERROR    *log.Logger
	CRITICAL *log.Logger
	FATAL    *log.Logger

	LOG      *log.Logger
	FEEDBACK *Feedback
)

Functions

func SetFlags 

func SetFlags(flags int)

SetFlags set the flags for the default logger. "log.Ldate | log.Ltime" by default.

func SetLogListeners 

func SetLogListeners(l ...LogListener)

SetLogListeners configures the default logger with one or more log listeners.

func SetLogOutput 

func SetLogOutput(handle io.Writer)

SetLogOutput set the log output for the default notepad. Discarded by default.

func SetLogThreshold 

func SetLogThreshold(threshold Threshold)

SetLogThreshold set the log threshold for the default notepad. Trace by default.

func SetPrefix 

func SetPrefix(prefix string)

SetPrefix set the prefix for the default logger. Empty by default.

func SetStdoutOutput 

func SetStdoutOutput(handle io.Writer)

SetStdoutOutput set the stdout output for the default notepad. Default is stdout.

func SetStdoutThreshold 

func SetStdoutThreshold(threshold Threshold)

SetStdoutThreshold set the standard output threshold for the default notepad. Info by default.

Types

type Counter 

type Counter struct {
	// contains filtered or unexported fields
}

Counter is an io.Writer that increments a counter on Write.

func (*Counter) Count 

func (c *Counter) Count() uint64

Count returns the current count.

func (*Counter) Reset 

func (c *Counter) Reset()

Reset resets the counter.

func (*Counter) Write 

func (c *Counter) Write(p []byte) (n int, err error)

type Feedback 

type Feedback struct {
	// contains filtered or unexported fields
}

Feedback writes plainly to the outHandle while logging with the standard extra information (date, file, etc).

func (*Feedback) Print 

func (fb *Feedback) Print(v ...interface{})

func (*Feedback) Printf 

func (fb *Feedback) Printf(format string, v ...interface{})

func (*Feedback) Println 

func (fb *Feedback) Println(v ...interface{})

type LogListener 

type LogListener func(t Threshold) io.Writer

A LogListener can ble supplied to a Notepad to listen on log writes for a given threshold. This can be used to capture log events in unit tests and similar. Note that this function will be invoked once for each log threshold. If the given threshold is not of interest to you, return nil. Note that these listeners will receive log events for a given threshold, even if the current configuration says not to log it. That way you can count ERRORs even if you don't print them to the console.

func LogCounter 

func LogCounter(counter *Counter, t1 Threshold) LogListener

LogCounter creates a LogListener that counts log statements >= the given threshold.

type Notepad 

type Notepad struct {
	TRACE    *log.Logger
	DEBUG    *log.Logger
	INFO     *log.Logger
	WARN     *log.Logger
	ERROR    *log.Logger
	CRITICAL *log.Logger
	FATAL    *log.Logger

	LOG      *log.Logger
	FEEDBACK *Feedback
	// contains filtered or unexported fields
}

Notepad is where you leave a note!

func NewNotepad 

func NewNotepad(
	outThreshold Threshold,
	logThreshold Threshold,
	outHandle, logHandle io.Writer,
	prefix string, flags int,
	logListeners ...LogListener,
) *Notepad

NewNotepad creates a new Notepad.

func (*Notepad) GetLogHandle 

func (n *Notepad) GetLogHandle() io.Writer

GetLogHandle gets the logHandle

func (*Notepad) GetLogThreshold 

func (n *Notepad) GetLogThreshold() Threshold

GetStdoutThreshold returns the defined Treshold for the log logger.

func (*Notepad) GetOutHandle 

func (n *Notepad) GetOutHandle() io.Writer

GetOutHandle gets the outHandle

func (*Notepad) GetStdoutThreshold 

func (n *Notepad) GetStdoutThreshold() Threshold

GetStdoutThreshold returns the Treshold for the stdout logger.

func (*Notepad) SetFlags 

func (n *Notepad) SetFlags(flags int)

SetFlags choose which flags the logger will display (after prefix and message level). See the package log for more informations on this.

func (*Notepad) SetLogOutput 

func (n *Notepad) SetLogOutput(handle io.Writer)

SetLogOutput changes the file where log messages are written.

func (*Notepad) SetLogThreshold 

func (n *Notepad) SetLogThreshold(threshold Threshold)

SetLogThreshold changes the threshold above which messages are written to the log file.

func (*Notepad) SetPrefix 

func (n *Notepad) SetPrefix(prefix string)

SetPrefix changes the prefix used by the notepad. Prefixes are displayed between brackets at the beginning of the line. An empty prefix won't be displayed at all.

func (*Notepad) SetStdoutOutput 

func (n *Notepad) SetStdoutOutput(handle io.Writer)

SetStdoutOutput set the stdout output for the notepad.

func (*Notepad) SetStdoutThreshold 

func (n *Notepad) SetStdoutThreshold(threshold Threshold)

SetStdoutThreshold changes the threshold above which messages are written to the standard output.

type Threshold 

type Threshold int
const (
	LevelTrace Threshold = iota
	LevelDebug
	LevelInfo
	LevelWarn
	LevelError
	LevelCritical
	LevelFatal
)

func GetLogThreshold 

func GetLogThreshold() Threshold

GetStdoutThreshold returns the defined Treshold for the log logger.

func GetStdoutThreshold 

func GetStdoutThreshold() Threshold

GetStdoutThreshold returns the Treshold for the stdout logger.

func LogThreshold 

func LogThreshold() Threshold

Level returns the current global log threshold.

func StdoutThreshold 

func StdoutThreshold() Threshold

Level returns the current global output threshold.

func (Threshold) String 

func (t Threshold) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.