Add good docs

Author: joeybloggs

doc.go

@@ -0,0 +1,130 @@
+/*
+Package log - is a simple, highly configurable, structured logging that is a near drop in replacement for the std library log.
+
+
+Usage
+
+    package main
+
+    import (
+        "github.com/go-playground/log"
+        "github.com/go-playground/log/handlers/console"
+    )
+
+    func main() {
+
+        cLog := console.New()
+
+        log.RegisterHandler(cLog, log.AllLevels...)
+
+        // Trace
+        defer log.Trace("trace").End()
+
+        log.Debug("debug")
+        log.Info("info")
+        log.Notice("notice")
+        log.Warn("warn")
+        log.Error("error")
+        // log.Panic("panic") // this will panic
+        log.Alert("alert")
+        // log.Fatal("fatal") // this will call os.Exit(1)
+
+        // logging with fields can be used with any of the above
+        log.WithFields(log.F("key", "value")).Info("test info")
+    }
+
+Adding your own Handler
+
+    package main
+
+    import (
+        "bytes"
+        "fmt"
+
+        "github.com/go-playground/log"
+    )
+
+    // CustomHandler is your custom handler
+    type CustomHandler struct {
+        // whatever properties you need
+        buffer uint // channel buffer
+    }
+
+    // Run starts the logger consuming on the returned channed
+    func (c *CustomHandler) Run() chan<- *log.Entry {
+
+        // in a big high traffic app, set a higher buffer
+        ch := make(chan *log.Entry, c.buffer)
+
+        // can run as many consumers on the channel as you want,
+        // depending on the buffer size or your needs
+        go func(entries <-chan *log.Entry) {
+
+            // below prints to os.Stderr but could marshal to JSON
+            // and send to central logging server
+            var e *log.Entry
+            b := new(bytes.Buffer)
+
+            for e = range entries {
+
+                b.Reset()
+                b.WriteString(e.Message)
+
+                for _, f := range e.Fields {
+                    fmt.Fprintf(b, " %s=%v", f.Key, f.Value)
+                }
+
+                fmt.Println(b.String())
+                e.WG.Done() // done writing the entry
+            }
+
+        }(ch)
+
+        return ch
+    }
+
+    func main() {
+
+        cLog := &CustomHandler{
+            buffer: 0,
+        }
+
+        log.RegisterHandler(cLog, log.AllLevels...)
+
+        // Trace
+        defer log.Trace("trace").End()
+
+        log.Debug("debug")
+        log.Info("info")
+        log.Notice("notice")
+        log.Warn("warn")
+        log.Error("error")
+        // log.Panic("panic") // this will panic
+        log.Alert("alert")
+        // log.Fatal("fatal") // this will call os.Exit(1)
+
+        // logging with fields can be used with any of the above
+        log.WithFields(log.F("key", "value")).Info("test info")
+    }
+
+Log Level Definitions
+
+    DebugLevel - Info useful to developers for debugging the application, not useful during operations.
+
+    TraceLevel - Info useful to developers for debugging the application and reporting on possible bottlenecks.
+
+    InfoLevel - Normal operational messages - may be harvested for reporting, measuring throughput, etc. - no action required.
+
+    NoticeLevel - Normal but significant condition. Events that are unusual but not error conditions - might be summarized in an email to developers or admins to spot potential problems - no immediate action required.
+
+    WarnLevel - Warning messages, not an error, but indication that an error will occur if action is not taken, e.g. file system 85% full - each item must be resolved within a given time.
+
+    ErrorLevel - Non-urgent failures, these should be relayed to developers or admins; each item must be resolved within a given time.
+
+    PanicLevel - A "panic" condition usually affecting multiple apps/servers/sites. At this level it would usually notify all tech staff on call.
+
+    AlertLevel - Action must be taken immediately. Should be corrected immediately, therefore notify staff who can fix the problem. An example would be the loss of a primary ISP connection.
+
+    FatalLevel - Should be corrected immediately, but indicates failure in a primary system, an example is a loss of a backup ISP connection. ( same as SYSLOG CRITICAL )
+*/
+package log