1 // Package logr defines abstract interfaces for logging. Packages can depend on
2 // these interfaces and callers can implement logging in whatever way is
5 // This design derives from Dave Cheney's blog:
6 // http://dave.cheney.net/2015/11/05/lets-talk-about-logging
8 // This is a BETA grade API. Until there is a significant 2nd implementation,
9 // I don't really know how it will change.
11 // The logging specifically makes it non-trivial to use format strings, to encourage
12 // attaching structured information instead of unstructured format strings.
16 // Logging is done using a Logger. Loggers can have name prefixes and named values
17 // attached, so that all log messages logged with that Logger have some base context
20 // The term "key" is used to refer to the name associated with a particular value, to
21 // disambiguate it from the general Logger name.
23 // For instance, suppose we're trying to reconcile the state of an object, and we want
24 // to log that we've made some decision.
26 // With the traditional log package, we might write
28 // "decided to set field foo to value %q for object %s/%s",
29 // targetValue, object.Namespace, object.Name)
31 // With logr's structured logging, we'd write
32 // // elsewhere in the file, set up the logger to log with the prefix of "reconcilers",
33 // // and the named value target-type=Foo, for extra context.
34 // log := mainLogger.WithName("reconcilers").WithValues("target-type", "Foo")
37 // log.Info("setting field foo on object", "value", targetValue, "object", object)
39 // Depending on our logging implementation, we could then make logging decisions based on field values
40 // (like only logging such events for objects in a certain namespace), or copy the structured
41 // information into a structured log store.
43 // For logging errors, Logger has a method called Error. Suppose we wanted to log an
44 // error while reconciling. With the traditional log package, we might write
45 // log.Errorf("unable to reconcile object %s/%s: %v", object.Namespace, object.Name, err)
47 // With logr, we'd instead write
48 // // assuming the above setup for log
49 // log.Error(err, "unable to reconcile object", "object", object)
51 // This functions similarly to:
52 // log.Info("unable to reconcile object", "error", err, "object", object)
54 // However, it ensures that a standard key for the error value ("error") is used across all
55 // error logging. Furthermore, certain implementations may choose to attach additional
56 // information (such as stack traces) on calls to Error, so it's preferred to use Error
59 // Parts of a log line
61 // Each log message from a Logger has four types of context:
62 // logger name, log verbosity, log message, and the named values.
64 // The Logger name constists of a series of name "segments" added by successive calls to WithName.
65 // These name segments will be joined in some way by the underlying implementation. It is strongly
66 // reccomended that name segements contain simple identifiers (letters, digits, and hyphen), and do
67 // not contain characters that could muddle the log output or confuse the joining operation (e.g.
68 // whitespace, commas, periods, slashes, brackets, quotes, etc).
70 // Log verbosity represents how little a log matters. Level zero, the default, matters most.
71 // Increasing levels matter less and less. Try to avoid lots of different verbosity levels,
72 // and instead provide useful keys, logger names, and log messages for users to filter on.
73 // It's illegal to pass a log level below zero.
75 // The log message consists of a constant message attached to the the log line. This
76 // should generally be a simple description of what's occuring, and should never be a format string.
78 // Variable information can then be attached using named values (key/value pairs). Keys are arbitrary
79 // strings, while values may be any Go value.
81 // Key Naming Conventions
83 // While users are generally free to use key names of their choice, it's generally best to avoid
84 // using the following keys, as they're frequently used by implementations:
86 // - `"error"`: the underlying error value in the `Error` method.
87 // - `"stacktrace"`: the stack trace associated with a particular log line or error
88 // (often from the `Error` message).
89 // - `"caller"`: the calling information (file/line) of a particular log line.
90 // - `"msg"`: the log message.
91 // - `"level"`: the log level.
92 // - `"ts"`: the timestamp for a log line.
94 // Implementations are encouraged to make use of these keys to represent the above
95 // concepts, when neccessary (for example, in a pure-JSON output form, it would be
96 // necessary to represent at least message and timestamp as ordinary named values).
99 // TODO: consider adding back in format strings if they're really needed
100 // TODO: consider other bits of zap/zapcore functionality like ObjectMarshaller (for arbitrary objects)
101 // TODO: consider other bits of glog functionality like Flush, InfoDepth, OutputStats
103 // InfoLogger represents the ability to log non-error messages, at a particular verbosity.
104 type InfoLogger interface {
105 // Info logs a non-error message with the given key/value pairs as context.
107 // The msg argument should be used to add some constant description to
108 // the log line. The key/value pairs can then be used to add additional
109 // variable information. The key/value pairs should alternate string
110 // keys and arbitrary values.
111 Info(msg string, keysAndValues ...interface{})
113 // Enabled tests whether this InfoLogger is enabled. For example,
114 // commandline flags might be used to set the logging verbosity and disable
119 // Logger represents the ability to log messages, both errors and not.
120 type Logger interface {
121 // All Loggers implement InfoLogger. Calling InfoLogger methods directly on
122 // a Logger value is equivalent to calling them on a V(0) InfoLogger. For
123 // example, logger.Info() produces the same result as logger.V(0).Info.
126 // Error logs an error, with the given message and key/value pairs as context.
127 // It functions similarly to calling Info with the "error" named value, but may
128 // have unique behavior, and should be preferred for logging errors (see the
129 // package documentations for more information).
131 // The msg field should be used to add context to any underlying error,
132 // while the err field should be used to attach the actual error that
133 // triggered this log line, if present.
134 Error(err error, msg string, keysAndValues ...interface{})
136 // V returns an InfoLogger value for a specific verbosity level. A higher
137 // verbosity level means a log message is less important. It's illegal to
138 // pass a log level less than zero.
139 V(level int) InfoLogger
141 // WithValues adds some key-value pairs of context to a logger.
142 // See Info for documentation on how key/value pairs work.
143 WithValues(keysAndValues ...interface{}) Logger
145 // WithName adds a new element to the logger's name.
146 // Successive calls with WithName continue to append
147 // suffixes to the logger's name. It's strongly reccomended
148 // that name segments contain only letters, digits, and hyphens
149 // (see the package documentation for more information).
150 WithName(name string) Logger