1 // Package log provides a structured logger. 2 // 3 // Deprecated: Use github.com/go-kit/log instead. 4 // 5 // Structured logging produces logs easily consumed later by humans or 6 // machines. Humans might be interested in debugging errors, or tracing 7 // specific requests. Machines might be interested in counting interesting 8 // events, or aggregating information for off-line processing. In both cases, 9 // it is important that the log messages are structured and actionable. 10 // Package log is designed to encourage both of these best practices. 11 // 12 // Basic Usage 13 // 14 // The fundamental interface is Logger. Loggers create log events from 15 // key/value data. The Logger interface has a single method, Log, which 16 // accepts a sequence of alternating key/value pairs, which this package names 17 // keyvals. 18 // 19 // type Logger interface { 20 // Log(keyvals ...interface{}) error 21 // } 22 // 23 // Here is an example of a function using a Logger to create log events. 24 // 25 // func RunTask(task Task, logger log.Logger) string { 26 // logger.Log("taskID", task.ID, "event", "starting task") 27 // ... 28 // logger.Log("taskID", task.ID, "event", "task complete") 29 // } 30 // 31 // The keys in the above example are "taskID" and "event". The values are 32 // task.ID, "starting task", and "task complete". Every key is followed 33 // immediately by its value. 34 // 35 // Keys are usually plain strings. Values may be any type that has a sensible 36 // encoding in the chosen log format. With structured logging it is a good 37 // idea to log simple values without formatting them. This practice allows 38 // the chosen logger to encode values in the most appropriate way. 39 // 40 // Contextual Loggers 41 // 42 // A contextual logger stores keyvals that it includes in all log events. 43 // Building appropriate contextual loggers reduces repetition and aids 44 // consistency in the resulting log output. With, WithPrefix, and WithSuffix 45 // add context to a logger. We can use With to improve the RunTask example. 46 // 47 // func RunTask(task Task, logger log.Logger) string { 48 // logger = log.With(logger, "taskID", task.ID) 49 // logger.Log("event", "starting task") 50 // ... 51 // taskHelper(task.Cmd, logger) 52 // ... 53 // logger.Log("event", "task complete") 54 // } 55 // 56 // The improved version emits the same log events as the original for the 57 // first and last calls to Log. Passing the contextual logger to taskHelper 58 // enables each log event created by taskHelper to include the task.ID even 59 // though taskHelper does not have access to that value. Using contextual 60 // loggers this way simplifies producing log output that enables tracing the 61 // life cycle of individual tasks. (See the Contextual example for the full 62 // code of the above snippet.) 63 // 64 // Dynamic Contextual Values 65 // 66 // A Valuer function stored in a contextual logger generates a new value each 67 // time an event is logged. The Valuer example demonstrates how this feature 68 // works. 69 // 70 // Valuers provide the basis for consistently logging timestamps and source 71 // code location. The log package defines several valuers for that purpose. 72 // See Timestamp, DefaultTimestamp, DefaultTimestampUTC, Caller, and 73 // DefaultCaller. A common logger initialization sequence that ensures all log 74 // entries contain a timestamp and source location looks like this: 75 // 76 // logger := log.NewLogfmtLogger(log.NewSyncWriter(os.Stdout)) 77 // logger = log.With(logger, "ts", log.DefaultTimestampUTC, "caller", log.DefaultCaller) 78 // 79 // Concurrent Safety 80 // 81 // Applications with multiple goroutines want each log event written to the 82 // same logger to remain separate from other log events. Package log provides 83 // two simple solutions for concurrent safe logging. 84 // 85 // NewSyncWriter wraps an io.Writer and serializes each call to its Write 86 // method. Using a SyncWriter has the benefit that the smallest practical 87 // portion of the logging logic is performed within a mutex, but it requires 88 // the formatting Logger to make only one call to Write per log event. 89 // 90 // NewSyncLogger wraps any Logger and serializes each call to its Log method. 91 // Using a SyncLogger has the benefit that it guarantees each log event is 92 // handled atomically within the wrapped logger, but it typically serializes 93 // both the formatting and output logic. Use a SyncLogger if the formatting 94 // logger may perform multiple writes per log event. 95 // 96 // Error Handling 97 // 98 // This package relies on the practice of wrapping or decorating loggers with 99 // other loggers to provide composable pieces of functionality. It also means 100 // that Logger.Log must return an error because some 101 // implementations—especially those that output log data to an io.Writer—may 102 // encounter errors that cannot be handled locally. This in turn means that 103 // Loggers that wrap other loggers should return errors from the wrapped 104 // logger up the stack. 105 // 106 // Fortunately, the decorator pattern also provides a way to avoid the 107 // necessity to check for errors every time an application calls Logger.Log. 108 // An application required to panic whenever its Logger encounters 109 // an error could initialize its logger as follows. 110 // 111 // fmtlogger := log.NewLogfmtLogger(log.NewSyncWriter(os.Stdout)) 112 // logger := log.LoggerFunc(func(keyvals ...interface{}) error { 113 // if err := fmtlogger.Log(keyvals...); err != nil { 114 // panic(err) 115 // } 116 // return nil 117 // }) 118 package log 119