package log import ( "fmt" "io" "net" "os" "reflect" "sync" "github.com/go-stack/stack" ) // Handler defines where and how log records are written. // A Logger prints its log records by writing to a Handler. // Handlers are composable, providing you great flexibility in combining // them to achieve the logging structure that suits your applications. type Handler interface { Log(r *Record) error } // FuncHandler returns a Handler that logs records with the given // function. func FuncHandler(fn func(r *Record) error) Handler { return funcHandler(fn) } type funcHandler func(r *Record) error func (h funcHandler) Log(r *Record) error { return h(r) } // StreamHandler writes log records to an io.Writer // with the given format. StreamHandler can be used // to easily begin writing log records to other // outputs. // // StreamHandler wraps itself with LazyHandler and SyncHandler // to evaluate Lazy objects and perform safe concurrent writes. func StreamHandler(wr io.Writer, fmtr Format) Handler { h := FuncHandler(func(r *Record) error { _, err := wr.Write(fmtr.Format(r)) return err }) return LazyHandler(SyncHandler(h)) } // SyncHandler can be wrapped around a handler to guarantee that // only a single Log operation can proceed at a time. It's necessary // for thread-safe concurrent writes. func SyncHandler(h Handler) Handler { var mu sync.Mutex return FuncHandler(func(r *Record) error { defer mu.Unlock() mu.Lock() return h.Log(r) }) } // FileHandler returns a handler which writes log records to the give file // using the given format. If the path // already exists, FileHandler will append to the given file. If it does not, // FileHandler will create the file with mode 0644. func FileHandler(path string, fmtr Format) (Handler, error) { f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644) if err != nil { return nil, err } return closingHandler{f, StreamHandler(f, fmtr)}, nil } // NetHandler opens a socket to the given address and writes records // over the connection. func NetHandler(network, addr string, fmtr Format) (Handler, error) { conn, err := net.Dial(network, addr) if err != nil { return nil, err } return closingHandler{conn, StreamHandler(conn, fmtr)}, nil } // XXX: closingHandler is essentially unused at the moment // it's meant for a future time when the Handler interface supports // a possible Close() operation type closingHandler struct { io.WriteCloser Handler } func (h *closingHandler) Close() error { return h.WriteCloser.Close() } // CallerFileHandler returns a Handler that adds the line number and file of // the calling function to the context with key "caller". func CallerFileHandler(h Handler) Handler { return FuncHandler(func(r *Record) error { r.Ctx = append(r.Ctx, "caller", fmt.Sprint(r.Call)) return h.Log(r) }) } // CallerFuncHandler returns a Handler that adds the calling function name to // the context with key "fn". func CallerFuncHandler(h Handler) Handler { return FuncHandler(func(r *Record) error { r.Ctx = append(r.Ctx, "fn", formatCall("%+n", r.Call)) return h.Log(r) }) } // This function is here to please go vet on Go < 1.8. func formatCall(format string, c stack.Call) string { return fmt.Sprintf(format, c) } // CallerStackHandler returns a Handler that adds a stack trace to the context // with key "stack". The stack trace is formated as a space separated list of // call sites inside matching []'s. The most recent call site is listed first. // Each call site is formatted according to format. See the documentation of // package github.com/go-stack/stack for the list of supported formats. func CallerStackHandler(format string, h Handler) Handler { return FuncHandler(func(r *Record) error { s := stack.Trace().TrimBelow(r.Call).TrimRuntime() if len(s) > 0 { r.Ctx = append(r.Ctx, "stack", fmt.Sprintf(format, s)) } return h.Log(r) }) } // FilterHandler returns a Handler that only writes records to the // wrapped Handler if the given function evaluates true. For example, // to only log records where the 'err' key is not nil: // // logger.SetHandler(FilterHandler(func(r *Record) bool { // for i := 0; i < len(r.Ctx); i += 2 { // if r.Ctx[i] == "err" { // return r.Ctx[i+1] != nil // } // } // return false // }, h)) // func FilterHandler(fn func(r *Record) bool, h Handler) Handler { return FuncHandler(func(r *Record) error { if fn(r) { return h.Log(r) } return nil }) } // MatchFilterHandler returns a Handler that only writes records // to the wrapped Handler if the given key in the logged // context matches the value. For example, to only log records // from your ui package: // // log.MatchFilterHandler("pkg", "app/ui", log.StdoutHandler) // func MatchFilterHandler(key string, value interface{}, h Handler) Handler { return FilterHandler(func(r *Record) (pass bool) { switch key { case r.KeyNames.Lvl: return r.Lvl == value case r.KeyNames.Time: return r.Time == value case r.KeyNames.Msg: return r.Msg == value } for i := 0; i < len(r.Ctx); i += 2 { if r.Ctx[i] == key { return r.Ctx[i+1] == value } } return false }, h) } // LvlFilterHandler returns a Handler that only writes // records which are less than the given verbosity // level to the wrapped Handler. For example, to only // log Error/Crit records: // // log.LvlFilterHandler(log.LvlError, log.StdoutHandler) // func LvlFilterHandler(maxLvl Lvl, h Handler) Handler { return FilterHandler(func(r *Record) (pass bool) { return r.Lvl <= maxLvl }, h) } // MultiHandler dispatches any write to each of its handlers. // This is useful for writing different types of log information // to different locations. For example, to log to a file and // standard error: // // log.MultiHandler( // log.Must.FileHandler("/var/log/app.log", log.LogfmtFormat()), // log.StderrHandler) // func MultiHandler(hs ...Handler) Handler { return FuncHandler(func(r *Record) error { for _, h := range hs { // what to do about failures? h.Log(r) } return nil }) } // FailoverHandler writes all log records to the first handler // specified, but will failover and write to the second handler if // the first handler has failed, and so on for all handlers specified. // For example you might want to log to a network socket, but failover // to writing to a file if the network fails, and then to // standard out if the file write fails: // // log.FailoverHandler( // log.Must.NetHandler("tcp", ":9090", log.JSONFormat()), // log.Must.FileHandler("/var/log/app.log", log.LogfmtFormat()), // log.StdoutHandler) // // All writes that do not go to the first handler will add context with keys of // the form "failover_err_{idx}" which explain the error encountered while // trying to write to the handlers before them in the list. func FailoverHandler(hs ...Handler) Handler { return FuncHandler(func(r *Record) error { var err error for i, h := range hs { err = h.Log(r) if err == nil { return nil } r.Ctx = append(r.Ctx, fmt.Sprintf("failover_err_%d", i), err) } return err }) } // ChannelHandler writes all records to the given channel. // It blocks if the channel is full. Useful for async processing // of log messages, it's used by BufferedHandler. func ChannelHandler(recs chan<- *Record) Handler { return FuncHandler(func(r *Record) error { recs <- r return nil }) } // BufferedHandler writes all records to a buffered // channel of the given size which flushes into the wrapped // handler whenever it is available for writing. Since these // writes happen asynchronously, all writes to a BufferedHandler // never return an error and any errors from the wrapped handler are ignored. func BufferedHandler(bufSize int, h Handler) Handler { recs := make(chan *Record, bufSize) go func() { for m := range recs { _ = h.Log(m) } }() return ChannelHandler(recs) } // LazyHandler writes all values to the wrapped handler after evaluating // any lazy functions in the record's context. It is already wrapped // around StreamHandler and SyslogHandler in this library, you'll only need // it if you write your own Handler. func LazyHandler(h Handler) Handler { return FuncHandler(func(r *Record) error { // go through the values (odd indices) and reassign // the values of any lazy fn to the result of its execution hadErr := false for i := 1; i < len(r.Ctx); i += 2 { lz, ok := r.Ctx[i].(Lazy) if ok { v, err := evaluateLazy(lz) if err != nil { hadErr = true r.Ctx[i] = err } else { if cs, ok := v.(stack.CallStack); ok { v = cs.TrimBelow(r.Call).TrimRuntime() } r.Ctx[i] = v } } } if hadErr { r.Ctx = append(r.Ctx, errorKey, "bad lazy") } return h.Log(r) }) } func evaluateLazy(lz Lazy) (interface{}, error) { t := reflect.TypeOf(lz.Fn) if t.Kind() != reflect.Func { return nil, fmt.Errorf("INVALID_LAZY, not func: %+v", lz.Fn) } if t.NumIn() > 0 { return nil, fmt.Errorf("INVALID_LAZY, func takes args: %+v", lz.Fn) } if t.NumOut() == 0 { return nil, fmt.Errorf("INVALID_LAZY, no func return val: %+v", lz.Fn) } value := reflect.ValueOf(lz.Fn) results := value.Call([]reflect.Value{}) if len(results) == 1 { return results[0].Interface(), nil } values := make([]interface{}, len(results)) for i, v := range results { values[i] = v.Interface() } return values, nil } // DiscardHandler reports success for all writes but does nothing. // It is useful for dynamically disabling logging at runtime via // a Logger's SetHandler method. func DiscardHandler() Handler { return FuncHandler(func(r *Record) error { return nil }) } // Must provides the following Handler creation functions // which instead of returning an error parameter only return a Handler // and panic on failure: FileHandler, NetHandler, SyslogHandler, SyslogNetHandler var Must muster func must(h Handler, err error) Handler { if err != nil { panic(err) } return h } type muster struct{} func (m muster) FileHandler(path string, fmtr Format) Handler { return must(FileHandler(path, fmtr)) } func (m muster) NetHandler(network, addr string, fmtr Format) Handler { return must(NetHandler(network, addr, fmtr)) }