diff options
Diffstat (limited to 'vendor/github.com/go-logr/logr/logr.go')
| -rw-r--r-- | vendor/github.com/go-logr/logr/logr.go | 146 |
1 files changed, 117 insertions, 29 deletions
diff --git a/vendor/github.com/go-logr/logr/logr.go b/vendor/github.com/go-logr/logr/logr.go index 520c4fe55..842428bd3 100644 --- a/vendor/github.com/go-logr/logr/logr.go +++ b/vendor/github.com/go-logr/logr/logr.go @@ -14,18 +14,15 @@ See the License for the specific language governing permissions and limitations under the License. */ -// Package logr defines abstract interfaces for logging. Packages can depend on -// these interfaces and callers can implement logging in whatever way is -// appropriate. -// // This design derives from Dave Cheney's blog: // http://dave.cheney.net/2015/11/05/lets-talk-about-logging // // This is a BETA grade API. Until there is a significant 2nd implementation, // I don't really know how it will change. -// -// The logging specifically makes it non-trivial to use format strings, to encourage -// attaching structured information instead of unstructured format strings. + +// Package logr defines abstract interfaces for logging. Packages can depend on +// these interfaces and callers can implement logging in whatever way is +// appropriate. // // Usage // @@ -40,17 +37,16 @@ limitations under the License. // we want to log that we've made some decision. // // With the traditional log package, we might write: -// log.Printf( -// "decided to set field foo to value %q for object %s/%s", +// log.Printf("decided to set field foo to value %q for object %s/%s", // targetValue, object.Namespace, object.Name) // // With logr's structured logging, we'd write: -// // elsewhere in the file, set up the logger to log with the prefix of "reconcilers", -// // and the named value target-type=Foo, for extra context. -// log := mainLogger.WithName("reconcilers").WithValues("target-type", "Foo") +// // elsewhere in the file, set up the logger to log with the prefix of +// // "reconcilers", and the named value target-type=Foo, for extra context. +// log := mainLogger.WithName("reconcilers").WithValues("target-type", "Foo") // -// // later on... -// log.Info("setting field foo on object", "value", targetValue, "object", object) +// // later on... +// log.Info("setting foo on object", "value", targetValue, "object", object) // // Depending on our logging implementation, we could then make logging decisions // based on field values (like only logging such events for objects in a certain @@ -78,9 +74,9 @@ limitations under the License. // Each log message from a Logger has four types of context: // logger name, log verbosity, log message, and the named values. // -// The Logger name constists of a series of name "segments" added by successive +// The Logger name consists of a series of name "segments" added by successive // calls to WithName. These name segments will be joined in some way by the -// underlying implementation. It is strongly reccomended that name segements +// underlying implementation. It is strongly recommended that name segments // contain simple identifiers (letters, digits, and hyphen), and do not contain // characters that could muddle the log output or confuse the joining operation // (e.g. whitespace, commas, periods, slashes, brackets, quotes, etc). @@ -91,8 +87,8 @@ limitations under the License. // and log messages for users to filter on. It's illegal to pass a log level // below zero. // -// The log message consists of a constant message attached to the the log line. -// This should generally be a simple description of what's occuring, and should +// The log message consists of a constant message attached to the log line. +// This should generally be a simple description of what's occurring, and should // never be a format string. // // Variable information can then be attached using named values (key/value @@ -115,24 +111,38 @@ limitations under the License. // generally best to avoid using the following keys, as they're frequently used // by implementations: // -// - `"caller"`: the calling information (file/line) of a particular log line. -// - `"error"`: the underlying error value in the `Error` method. -// - `"level"`: the log level. -// - `"logger"`: the name of the associated logger. -// - `"msg"`: the log message. -// - `"stacktrace"`: the stack trace associated with a particular log line or -// error (often from the `Error` message). -// - `"ts"`: the timestamp for a log line. +// * `"caller"`: the calling information (file/line) of a particular log line. +// * `"error"`: the underlying error value in the `Error` method. +// * `"level"`: the log level. +// * `"logger"`: the name of the associated logger. +// * `"msg"`: the log message. +// * `"stacktrace"`: the stack trace associated with a particular log line or +// error (often from the `Error` message). +// * `"ts"`: the timestamp for a log line. // // Implementations are encouraged to make use of these keys to represent the -// above concepts, when neccessary (for example, in a pure-JSON output form, it +// above concepts, when necessary (for example, in a pure-JSON output form, it // would be necessary to represent at least message and timestamp as ordinary // named values). +// +// Implementations may choose to give callers access to the underlying +// logging implementation. The recommended pattern for this is: +// // Underlier exposes access to the underlying logging implementation. +// // Since callers only have a logr.Logger, they have to know which +// // implementation is in use, so this interface is less of an abstraction +// // and more of way to test type conversion. +// type Underlier interface { +// GetUnderlying() <underlying-type> +// } package logr +import ( + "context" +) + // TODO: consider adding back in format strings if they're really needed // TODO: consider other bits of zap/zapcore functionality like ObjectMarshaller (for arbitrary objects) -// TODO: consider other bits of glog functionality like Flush, InfoDepth, OutputStats +// TODO: consider other bits of glog functionality like Flush, OutputStats // Logger represents the ability to log messages, both errors and not. type Logger interface { @@ -171,8 +181,86 @@ type Logger interface { // WithName adds a new element to the logger's name. // Successive calls with WithName continue to append - // suffixes to the logger's name. It's strongly reccomended + // suffixes to the logger's name. It's strongly recommended // that name segments contain only letters, digits, and hyphens // (see the package documentation for more information). WithName(name string) Logger } + +// InfoLogger provides compatibility with code that relies on the v0.1.0 +// interface. +// +// Deprecated: InfoLogger is an artifact of early versions of this API. New +// users should never use it and existing users should use Logger instead. This +// will be removed in a future release. +type InfoLogger = Logger + +type contextKey struct{} + +// FromContext returns a Logger constructed from ctx or nil if no +// logger details are found. +func FromContext(ctx context.Context) Logger { + if v, ok := ctx.Value(contextKey{}).(Logger); ok { + return v + } + + return nil +} + +// FromContextOrDiscard returns a Logger constructed from ctx or a Logger +// that discards all messages if no logger details are found. +func FromContextOrDiscard(ctx context.Context) Logger { + if v, ok := ctx.Value(contextKey{}).(Logger); ok { + return v + } + + return Discard() +} + +// NewContext returns a new context derived from ctx that embeds the Logger. +func NewContext(ctx context.Context, l Logger) context.Context { + return context.WithValue(ctx, contextKey{}, l) +} + +// CallDepthLogger represents a Logger that knows how to climb the call stack +// to identify the original call site and can offset the depth by a specified +// number of frames. This is useful for users who have helper functions +// between the "real" call site and the actual calls to Logger methods. +// Implementations that log information about the call site (such as file, +// function, or line) would otherwise log information about the intermediate +// helper functions. +// +// This is an optional interface and implementations are not required to +// support it. +type CallDepthLogger interface { + Logger + + // WithCallDepth returns a Logger that will offset the call stack by the + // specified number of frames when logging call site information. If depth + // is 0 the attribution should be to the direct caller of this method. If + // depth is 1 the attribution should skip 1 call frame, and so on. + // Successive calls to this are additive. + WithCallDepth(depth int) Logger +} + +// WithCallDepth returns a Logger that will offset the call stack by the +// specified number of frames when logging call site information, if possible. +// This is useful for users who have helper functions between the "real" call +// site and the actual calls to Logger methods. If depth is 0 the attribution +// should be to the direct caller of this function. If depth is 1 the +// attribution should skip 1 call frame, and so on. Successive calls to this +// are additive. +// +// If the underlying log implementation supports the CallDepthLogger interface, +// the WithCallDepth method will be called and the result returned. If the +// implementation does not support CallDepthLogger, the original Logger will be +// returned. +// +// Callers which care about whether this was supported or not should test for +// CallDepthLogger support themselves. +func WithCallDepth(logger Logger, depth int) Logger { + if decorator, ok := logger.(CallDepthLogger); ok { + return decorator.WithCallDepth(depth) + } + return logger +} |