cmd/bpa-operator/vendor/github.com/go-logr/logr/README.md

   1 # A more minimal logging API for Go
   2
   3 Before you consider this package, please read [this blog post by the inimitable
   4 Dave Cheney](http://dave.cheney.net/2015/11/05/lets-talk-about-logging).  I
   5 really appreciate what he has to say, and it largely aligns with my own
   6 experiences.  Too many choices of levels means inconsistent logs.
   7
   8 This package offers a purely abstract interface, based on these ideas but with
   9 a few twists.  Code can depend on just this interface and have the actual
  10 logging implementation be injected from callers.  Ideally only `main()` knows
  11 what logging implementation is being used.
  12
  13 # Differences from Dave's ideas
  14
  15 The main differences are:
  16
  17 1) Dave basically proposes doing away with the notion of a logging API in favor
  18 of `fmt.Printf()`.  I disagree, especially when you consider things like output
  19 locations, timestamps, file and line decorations, and structured logging.  I
  20 restrict the API to just 2 types of logs: info and error.
  21
  22 Info logs are things you want to tell the user which are not errors.  Error
  23 logs are, well, errors.  If your code receives an `error` from a subordinate
  24 function call and is logging that `error` *and not returning it*, use error
  25 logs.
  26
  27 2) Verbosity-levels on info logs.  This gives developers a chance to indicate
  28 arbitrary grades of importance for info logs, without assigning names with
  29 semantic meaning such as "warning", "trace", and "debug".  Superficially this
  30 may feel very similar, but the primary difference is the lack of semantics.
  31 Because verbosity is a numerical value, it's safe to assume that an app running
  32 with higher verbosity means more (and less important) logs will be generated.
  33
  34 This is a BETA grade API.  I have implemented it for
  35 [glog](https://godoc.org/github.com/golang/glog). Until there is a significant
  36 2nd implementation, I don't really know how it will change.