12 DefaultOutput = os.Stderr
19 // This is a special level used to indicate that no level has been
20 // set and allow for a default to be used.
23 // The most verbose level. Intended to be used for the tracing of actions
24 // in code, such as function enters/exits, etc.
27 // For programmer lowlevel analysis.
30 // For information about steady state operations.
33 // For information about rare but handled events.
36 // For information about unrecoverable events.
40 // When processing a value of this type, the logger automatically treats the first
41 // argument as a Printf formatting string and passes the rest as the values to be
42 // formatted. For example: L.Info(Fmt{"%d beans/day", beans}). This is a simple
43 // convience type for when formatting is required.
44 type Format []interface{}
46 // Fmt returns a Format type. This is a convience function for creating a Format
48 func Fmt(str string, args ...interface{}) Format {
49 return append(Format{str}, args...)
52 // LevelFromString returns a Level type for the named log level, or "NoLevel" if
53 // the level string is invalid. This facilitates setting the log level via
54 // config or environment variable by name in a predictable way.
55 func LevelFromString(levelStr string) Level {
56 // We don't care about case. Accept "INFO" or "info"
57 levelStr = strings.ToLower(strings.TrimSpace(levelStr))
74 // The main Logger interface. All code should code against this interface only.
75 type Logger interface {
76 // Args are alternating key, val pairs
77 // keys must be strings
78 // vals can be any type, but display is implementation specific
79 // Emit a message and key/value pairs at the TRACE level
80 Trace(msg string, args ...interface{})
82 // Emit a message and key/value pairs at the DEBUG level
83 Debug(msg string, args ...interface{})
85 // Emit a message and key/value pairs at the INFO level
86 Info(msg string, args ...interface{})
88 // Emit a message and key/value pairs at the WARN level
89 Warn(msg string, args ...interface{})
91 // Emit a message and key/value pairs at the ERROR level
92 Error(msg string, args ...interface{})
94 // Indicate if TRACE logs would be emitted. This and the other Is* guards
95 // are used to elide expensive logging code based on the current level.
98 // Indicate if DEBUG logs would be emitted. This and the other Is* guards
101 // Indicate if INFO logs would be emitted. This and the other Is* guards
104 // Indicate if WARN logs would be emitted. This and the other Is* guards
107 // Indicate if ERROR logs would be emitted. This and the other Is* guards
110 // Creates a sublogger that will always have the given key/value pairs
111 With(args ...interface{}) Logger
113 // Create a logger that will prepend the name string on the front of all messages.
114 // If the logger already has a name, the new value will be appended to the current
115 // name. That way, a major subsystem can use this to decorate all it's own logs
116 // without losing context.
117 Named(name string) Logger
119 // Create a logger that will prepend the name string on the front of all messages.
120 // This sets the name of the logger to the value directly, unlike Named which honor
121 // the current name as well.
122 ResetNamed(name string) Logger
124 // Updates the level. This should affect all sub-loggers as well. If an
125 // implementation cannot update the level on the fly, it should no-op.
126 SetLevel(level Level)
128 // Return a value that conforms to the stdlib log.Logger interface
129 StandardLogger(opts *StandardLoggerOptions) *log.Logger
132 type StandardLoggerOptions struct {
133 // Indicate that some minimal parsing should be done on strings to try
134 // and detect their level and re-emit them.
135 // This supports the strings like [ERROR], [ERR] [TRACE], [WARN], [INFO],
136 // [DEBUG] and strip it off before reapplying it.
140 type LoggerOptions struct {
141 // Name of the subsystem to prefix logs with
144 // The threshold for the logger. Anything less severe is supressed
147 // Where to write the logs to. Defaults to os.Stderr if nil
150 // An optional mutex pointer in case Output is shared
153 // Control if the output should be in JSON.
156 // Include file and line information in each log line
159 // The time format to use instead of the default