const (
// LogError is the special value used for Error log entries.
LogError = LogType("ERROR")
// LogInfo is the special value used for Info log entries.
LogInfo = LogType("INFO")
)
DefaultConfig is the global default logging configuration for a unit test. It is used by NewTestContext and k8s.io/klogr/testing/init.
var DefaultConfig = NewConfig()
func NewLogger(t TL, c *Config) logr.Logger
NewLogger constructs a new logger for the given test interface.
Beware that testing.T does not support logging after the test that it was created for has completed. If a test leaks goroutines and those goroutines log something after test completion, that output will be printed via the global klog logger with `<test name> leaked goroutine` as prefix.
Verbosity can be modified at any time through the Config.V and Config.VModule API.
▹ Example
func NewTestContext(tl TL) (logr.Logger, context.Context)
NewTestContext returns a logger and context for use in a unit test case or benchmark. The tl parameter can be a testing.T or testing.B pointer that will receive all log output. Importing k8s.io/klogr/testing/init will add command line flags that modify the configuration of that log output.
Buffer stores log entries as formatted text and structured data. It is safe to use this concurrently.
type Buffer interface {
// String returns the log entries in a format that is similar to the
// klog text output.
String() string
// Data returns the log entries as structs.
Data() Log
}
BufferTL implements TL with an in-memory buffer.
type BufferTL struct {
strings.Builder
}
func (n *BufferTL) Helper()
func (n *BufferTL) Log(args ...interface{})
Config influences logging in a test logger. To make this configurable via command line flags, instantiate this once per program and use AddFlags to bind command line flags to the instance before passing it to NewTestContext.
Must be constructed with NewConfig.
type Config struct {
// contains filtered or unexported fields
}
func NewConfig(opts ...ConfigOption) *Config
NewConfig returns a configuration with recommended defaults and optional modifications. Command line flags are not bound to any FlagSet yet.
func (c *Config) AddFlags(fs *flag.FlagSet)
AddFlags registers the command line flags that control the configuration.
func (c *Config) VModule() flag.Value
VModule returns a value instance that can be used to query (via String) or modify (via Set) the vmodule settings. This is thread-safe and can be done at runtime.
func (c *Config) Verbosity() flag.Value
Verbosity returns a value instance that can be used to query (via String) or modify (via Set) the verbosity threshold. This is thread-safe and can be done at runtime.
▹ Example
ConfigOption implements functional parameters for NewConfig.
type ConfigOption func(co *configOptions)
func AnyToString(anyToString func(value interface{}) string) ConfigOption
AnyToString overrides the default formatter for values that are not supported directly by klog. The default is `fmt.Sprintf("%+v")`. The formatter must not panic.
func BufferLogs(enabled bool) ConfigOption
BufferLogs controls whether log entries are captured in memory in addition to being printed. Off by default. Unit tests that want to verify that log entries are emitted as expected can turn this on and then retrieve the captured log through the Underlier LogSink interface.
func VModuleFlagName(name string) ConfigOption
VModulFlagName overrides the default -testing.vmodule for the per-module verbosity levels.
func Verbosity(level int) ConfigOption
Verbosity overrides the default verbosity level of 5. That default is higher than in klog itself because it enables logging entries for "the steps leading up to errors and warnings" and "troubleshooting" (see https://github.com/kubernetes/community/blob/9406b4352fe2d5810cb21cc3cb059ce5886de157/contributors/devel/sig-instrumentation/logging.md#logging-conventions), which is useful when debugging a failed test. `go test` only shows the log output for failed tests. To see all output, use `go test -v`.
func VerbosityFlagName(name string) ConfigOption
VerbosityFlagName overrides the default -testing.v for the verbosity level.
Log contains log entries in the order in which they were generated.
type Log []LogEntry
func (l Log) DeepCopy() Log
DeepCopy returns a copy of the log. The error instance and key/value pairs remain shared.
LogEntry represents all information captured for a log entry.
type LogEntry struct {
// Timestamp stores the time when the log entry was created.
Timestamp time.Time
// Type is either LogInfo or LogError.
Type LogType
// Prefix contains the WithName strings concatenated with a slash.
Prefix string
// Message is the fixed log message string.
Message string
// Verbosity is always 0 for LogError.
Verbosity int
// Err is always nil for LogInfo. It may or may not be
// nil for LogError.
Err error
// WithKVList are the concatenated key/value pairs from WithValues
// calls. It's guaranteed to have an even number of entries because
// the logger ensures that when WithValues is called.
WithKVList []interface{}
// ParameterKVList are the key/value pairs passed into the call,
// without any validation.
ParameterKVList []interface{}
}
LogType determines whether a log entry was created with an Error or Info call.
type LogType string
NopTL implements TL with empty stubs. It can be used when only capturing output in memory is relevant.
type NopTL struct{}
func (n NopTL) Helper()
func (n NopTL) Log(...interface{})
TL is the relevant subset of testing.TB.
type TL interface {
Helper()
Log(args ...interface{})
}
Underlier is implemented by the LogSink of this logger. It provides access to additional APIs that are normally hidden behind the Logger API.
type Underlier interface {
// GetUnderlying returns the testing instance that logging goes to.
// It returns nil when the test has completed already.
GetUnderlying() TL
// GetBuffer grants access to the in-memory copy of the log entries.
GetBuffer() Buffer
}
▹ Example