| 12 | 12 |
//
|
| 13 | 13 |
// Usage
|
| 14 | 14 |
//
|
| 15 | |
// Logging is done using a Logger. Loggers can have name prefixes and tags attached,
|
| 16 | |
// so that all log messages logged with that Logger have some base context associated.
|
|
15 |
// Logging is done using a Logger. Loggers can have name prefixes and named values
|
|
16 |
// attached, so that all log messages logged with that Logger have some base context
|
|
17 |
// associated.
|
|
18 |
//
|
|
19 |
// The term "key" is used to refer to the name associated with a particular value, to
|
|
20 |
// disambiguate it from the general Logger name.
|
| 17 | 21 |
//
|
| 18 | 22 |
// For instance, suppose we're trying to reconcile the state of an object, and we want
|
| 19 | 23 |
// to log that we've made some decision.
|
|
| 25 | 29 |
//
|
| 26 | 30 |
// With logr's structured logging, we'd write
|
| 27 | 31 |
// // elsewhere in the file, set up the logger to log with the prefix of "reconcilers",
|
| 28 | |
// // and the tag target-type=Foo, for extra context.
|
|
32 |
// // and the named value target-type=Foo, for extra context.
|
| 29 | 33 |
// log := mainLogger.WithName("reconcilers").WithTag("target-type", "Foo")
|
| 30 | 34 |
//
|
| 31 | 35 |
// // later on...
|
|
| 46 | 50 |
// This functions similarly to:
|
| 47 | 51 |
// log.Info("unable to reconcile object", "error", err, "object", object)
|
| 48 | 52 |
//
|
| 49 | |
// However, it ensures that a standard tag ("error") is used across all error logging. Furthermore,
|
| 50 | |
// certain implementations may choose to attach additional information (such as stack traces) on
|
| 51 | |
// calls to Error, so it's preferred to use Error to log errors.
|
|
53 |
// However, it ensures that a standard key for the error value ("error") is used across all
|
|
54 |
// error logging. Furthermore, certain implementations may choose to attach additional
|
|
55 |
// information (such as stack traces) on calls to Error, so it's preferred to use Error
|
|
56 |
// to log errors.
|
| 52 | 57 |
//
|
| 53 | 58 |
// Parts of a log line
|
| 54 | 59 |
//
|
| 55 | 60 |
// Each log message from a Logger has four types of context:
|
| 56 | |
// logger name, log verbosity, log message, and key-value pairs.
|
|
61 |
// logger name, log verbosity, log message, and the named values.
|
| 57 | 62 |
//
|
| 58 | |
// The Logger name is constists of a series of name "segments" added by successive calls to WithName.
|
|
63 |
// The Logger name constists of a series of name "segments" added by successive calls to WithName.
|
| 59 | 64 |
// These name segments will be joined in some way by the underlying implementation. It is strongly
|
| 60 | 65 |
// reccomended that name segements contain simple identifiers (letters, digits, and hyphen), and do
|
| 61 | 66 |
// not contain characters that could muddle the log output or confuse the joining operation (e.g.
|
|
| 68 | 73 |
// The log message consists of a constant message attached to the the log line. This
|
| 69 | 74 |
// should generally be a simple description of what's occuring, and should never be a format string.
|
| 70 | 75 |
//
|
| 71 | |
// Variable information can then be attached using key/value pairs. Keys are arbitrary strings,
|
| 72 | |
// and values may be any Go value.
|
|
76 |
// Variable information can then be attached using named values (key/value pairs). Keys are arbitrary
|
|
77 |
// strings, while values may be any Go value.
|
| 73 | 78 |
package logr
|
| 74 | 79 |
|
| 75 | 80 |
// TODO: consider adding back in format strings if they're really needed
|
|
| 100 | 105 |
InfoLogger
|
| 101 | 106 |
|
| 102 | 107 |
// Error logs an error, with the given message and key/value pairs as context.
|
| 103 | |
// It functions similarly to calling Info with the "error" tag, but may have
|
| 104 | |
// unique behavior, and should be preferred for logging errors (see the package
|
|
108 |
// It functions similarly to calling Info with the "error" named value, but may
|
| 105 | 109 |
// documentations for more information).
|
| 106 | |
//
|
|
110 |
// package documentations for more information).
|
| 107 | 111 |
// The msg field should be used to add context to any underlying error,
|
| 108 | 112 |
// while the err field should be used to attach the actual error that
|
| 109 | 113 |
// triggered this log line, if present.
|
|
| 113 | 117 |
// verbosity level means a log message is less important.
|
| 114 | 118 |
V(level int) InfoLogger
|
| 115 | 119 |
|
| 116 | |
// WithTags adds some key-value pairs of context to a logger.
|
|
120 |
// WithValues adds some key-value pairs of context to a logger.
|
| 117 | 121 |
// See Info for documentation on how key/value pairs work.
|
| 118 | |
WithTags(keysAndValues ...interface{}) Logger
|
|
122 |
WithValues(keysAndValues ...interface{}) Logger
|
| 119 | 123 |
|
| 120 | 124 |
// WithName adds a new element to the logger's name.
|
| 121 | 125 |
// Successive calls with WithName continue to append
|