Codebase list golang-github-go-kit-kit / 6d9bb5f
log: Add docs for new types and functions. Chris Hines 7 years ago
3 changed file(s) with 48 addition(s) and 16 deletion(s). Raw diff Collapse all Expand all
1717 // level.Error(logger).Log("value", value)
1818 // }
1919 //
20 // The leveled logger allows precise control over what should happen if a log
21 // event is emitted without a level key, or if a squelched level is used.
22 // Check the Option functions for details.
20 // NewFilter allows precise control over what happens when a log event is
21 // emitted without a level key, or if a squelched level is used. Check the
22 // Option functions for details.
2323 package level
33
44 // Error returns a logger that includes a Key/ErrorValue pair.
55 func Error(logger log.Logger) log.Logger {
6 return log.NewContext(logger).WithPrefix(key, errorValue)
6 return log.NewContext(logger).WithPrefix(Key(), ErrorValue())
77 }
88
99 // Warn returns a logger that includes a Key/WarnValue pair.
1010 func Warn(logger log.Logger) log.Logger {
11 return log.NewContext(logger).WithPrefix(key, warnValue)
11 return log.NewContext(logger).WithPrefix(Key(), WarnValue())
1212 }
1313
1414 // Info returns a logger that includes a Key/InfoValue pair.
1515 func Info(logger log.Logger) log.Logger {
16 return log.NewContext(logger).WithPrefix(key, infoValue)
16 return log.NewContext(logger).WithPrefix(Key(), InfoValue())
1717 }
1818
1919 // Debug returns a logger that includes a Key/DebugValue pair.
2020 func Debug(logger log.Logger) log.Logger {
21 return log.NewContext(logger).WithPrefix(key, debugValue)
21 return log.NewContext(logger).WithPrefix(Key(), DebugValue())
2222 }
2323
2424 // NewFilter wraps next and implements level filtering. See the commentary on
122122 return func(l *logger) { l.errNoLevel = err }
123123 }
124124
125 // NewInjector wraps next and returns a logger that adds a Key/level pair to
126 // the beginning of log events that don't already contain a level.
125127 func NewInjector(next log.Logger, level Value) log.Logger {
126128 return &injector{
127129 next: next,
146148 return l.next.Log(kvs...)
147149 }
148150
151 // Value is the interface that each of the canonical level values implement.
152 // It contains unexported methods that prevent types from other packages from
153 // implementing it and guaranteeing that NewFilter can distinguish the levels
154 // defined in this package from all other values.
149155 type Value interface {
150156 String() string
151157 levelVal()
152158 }
153159
154 func Key() interface{} { return key }
160 // Key returns the unique key added to log events by the loggers in this
161 // package.
162 func Key() interface{} { return key }
163
164 // ErrorValue returns the unique value added to log events by Error.
155165 func ErrorValue() Value { return errorValue }
156 func WarnValue() Value { return warnValue }
157 func InfoValue() Value { return infoValue }
166
167 // WarnValue returns the unique value added to log events by Warn.
168 func WarnValue() Value { return warnValue }
169
170 // InfoValue returns the unique value added to log events by Info.
171 func InfoValue() Value { return infoValue }
172
173 // DebugValue returns the unique value added to log events by Warn.
158174 func DebugValue() Value { return debugValue }
159175
160176 var (
161 key interface{} = "level"
162 errorValue = &levelValue{level: levelError, name: "error"}
163 warnValue = &levelValue{level: levelWarn, name: "warn"}
164 infoValue = &levelValue{level: levelInfo, name: "info"}
165 debugValue = &levelValue{level: levelDebug, name: "debug"}
177 // key is of type interfae{} so that it allocates once during package
178 // initialization and avoids allocating every type the value is added to a
179 // []interface{} later.
180 key interface{} = "level"
181
182 errorValue = &levelValue{level: levelError, name: "error"}
183 warnValue = &levelValue{level: levelWarn, name: "warn"}
184 infoValue = &levelValue{level: levelInfo, name: "info"}
185 debugValue = &levelValue{level: levelDebug, name: "debug"}
166186 )
167187
168188 type level byte
214214 if got, want := len(output), 4; got != want {
215215 t.Errorf("missing level not injected: got len==%d, want len==%d", got, want)
216216 }
217 if got, want := output[0], level.Key(); got != want {
218 t.Errorf("wrong level key: got %#v, want %#v", got, want)
219 }
220 if got, want := output[1], level.InfoValue(); got != want {
221 t.Errorf("wrong level value: got %#v, want %#v", got, want)
222 }
217223
218224 level.Error(logger).Log("foo", "bar")
219225 if got, want := len(output), 4; got != want {
220226 t.Errorf("leveled record modified: got len==%d, want len==%d", got, want)
221227 }
222 }
228 if got, want := output[0], level.Key(); got != want {
229 t.Errorf("wrong level key: got %#v, want %#v", got, want)
230 }
231 if got, want := output[1], level.ErrorValue(); got != want {
232 t.Errorf("wrong level value: got %#v, want %#v", got, want)
233 }
234 }