From 18cdd3ac11ed6fd58998bf83e171b3282a01f2bb Mon Sep 17 00:00:00 2001 From: Patrick Ohly Date: Thu, 26 Oct 2023 13:19:33 +0200 Subject: [PATCH] promote experimental code to stable ktesting is heavily used in Kubernetes already for testing. The test package is also used. The textlogger is not used that much yet because it was still experimental (and thus no replacement for normal klog), but it's simple and unlikely to need any breaking API changes. --- ktesting/init/init.go | 5 --- ktesting/options.go | 45 --------------------------- ktesting/setup.go | 10 ------ ktesting/testinglogger.go | 65 --------------------------------------- test/output.go | 27 ---------------- test/zapr.go | 10 ------ textlogger/options.go | 35 --------------------- textlogger/textlogger.go | 15 --------- 8 files changed, 212 deletions(-) diff --git a/ktesting/init/init.go b/ktesting/init/init.go index 7eb4dc675..3ee86f63a 100644 --- a/ktesting/init/init.go +++ b/ktesting/init/init.go @@ -17,11 +17,6 @@ limitations under the License. // Package init registers the command line flags for k8s.io/klogr/testing in // the flag.CommandLine. This is done during initialization, so merely // importing it is enough. -// -// # Experimental -// -// Notice: This package is EXPERIMENTAL and may be changed or removed in a -// later release. package init import ( diff --git a/ktesting/options.go b/ktesting/options.go index d039c40b0..868446c39 100644 --- a/ktesting/options.go +++ b/ktesting/options.go @@ -29,11 +29,6 @@ import ( // bind command line flags to the instance before passing it to NewTestContext. // // Must be constructed with NewConfig. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type Config struct { vstate *verbosity.VState co configOptions @@ -54,11 +49,6 @@ func (c *Config) VModule() flag.Value { } // ConfigOption implements functional parameters for NewConfig. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type ConfigOption func(co *configOptions) type configOptions struct { @@ -72,11 +62,6 @@ type configOptions struct { // 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. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func AnyToString(anyToString func(value interface{}) string) ConfigOption { return func(co *configOptions) { co.anyToString = anyToString @@ -84,11 +69,6 @@ func AnyToString(anyToString func(value interface{}) string) ConfigOption { } // VerbosityFlagName overrides the default -testing.v for the verbosity level. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func VerbosityFlagName(name string) ConfigOption { return func(co *configOptions) { co.verbosityFlagName = name @@ -97,11 +77,6 @@ func VerbosityFlagName(name string) ConfigOption { // VModulFlagName overrides the default -testing.vmodule for the per-module // verbosity levels. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func VModuleFlagName(name string) ConfigOption { return func(co *configOptions) { co.vmoduleFlagName = name @@ -114,11 +89,6 @@ func VModuleFlagName(name string) ConfigOption { // 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`. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func Verbosity(level int) ConfigOption { return func(co *configOptions) { co.verbosityDefault = level @@ -129,11 +99,6 @@ func Verbosity(level int) ConfigOption { // 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. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func BufferLogs(enabled bool) ConfigOption { return func(co *configOptions) { co.bufferLogs = enabled @@ -142,11 +107,6 @@ func BufferLogs(enabled bool) ConfigOption { // NewConfig returns a configuration with recommended defaults and optional // modifications. Command line flags are not bound to any FlagSet yet. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func NewConfig(opts ...ConfigOption) *Config { c := &Config{ co: configOptions{ @@ -165,11 +125,6 @@ func NewConfig(opts ...ConfigOption) *Config { } // AddFlags registers the command line flags that control the configuration. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func (c *Config) AddFlags(fs *flag.FlagSet) { fs.Var(c.vstate.V(), c.co.verbosityFlagName, "number for the log level verbosity of the testing logger") fs.Var(c.vstate.VModule(), c.co.vmoduleFlagName, "comma-separated list of pattern=N log level settings for files matching the patterns") diff --git a/ktesting/setup.go b/ktesting/setup.go index 16b218ecd..bf1d03447 100644 --- a/ktesting/setup.go +++ b/ktesting/setup.go @@ -24,22 +24,12 @@ import ( // DefaultConfig is the global default logging configuration for a unit // test. It is used by NewTestContext and k8s.io/klogr/testing/init. -// -// # Experimental -// -// Notice: This variable is EXPERIMENTAL and may be changed or removed in a -// later release. var DefaultConfig = NewConfig() // 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. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func NewTestContext(tl TL) (logr.Logger, context.Context) { logger := NewLogger(tl, DefaultConfig) ctx := logr.NewContext(context.Background(), logger) diff --git a/ktesting/testinglogger.go b/ktesting/testinglogger.go index 14a22bf40..da0e2b81a 100644 --- a/ktesting/testinglogger.go +++ b/ktesting/testinglogger.go @@ -34,11 +34,6 @@ limitations under the License. // // Serialization of the structured log parameters is done in the same way // as for klog.InfoS. -// -// # Experimental -// -// Notice: This package is EXPERIMENTAL and may be changed or removed in a -// later release. package ktesting import ( @@ -58,11 +53,6 @@ import ( ) // TL is the relevant subset of testing.TB. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type TL interface { Helper() Log(args ...interface{}) @@ -70,11 +60,6 @@ type TL interface { // NopTL implements TL with empty stubs. It can be used when only capturing // output in memory is relevant. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type NopTL struct{} func (n NopTL) Helper() {} @@ -83,11 +68,6 @@ func (n NopTL) Log(args ...interface{}) {} var _ TL = NopTL{} // BufferTL implements TL with an in-memory buffer. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type BufferTL struct { strings.Builder } @@ -109,11 +89,6 @@ var _ TL = &BufferTL{} // // Verbosity can be modified at any time through the Config.V and // Config.VModule API. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. func NewLogger(t TL, c *Config) logr.Logger { l := tlogger{ shared: &tloggerShared{ @@ -141,11 +116,6 @@ func NewLogger(t TL, c *Config) logr.Logger { // Buffer stores log entries as formatted text and structured data. // It is safe to use this concurrently. -// -// # Experimental -// -// Notice: This interface is EXPERIMENTAL and may be changed or removed in a -// later release. type Buffer interface { // String returns the log entries in a format that is similar to the // klog text output. @@ -156,20 +126,10 @@ type Buffer interface { } // Log contains log entries in the order in which they were generated. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type Log []LogEntry // DeepCopy returns a copy of the log. The error instance and key/value // pairs remain shared. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func (l Log) DeepCopy() Log { log := make(Log, 0, len(l)) log = append(log, l...) @@ -177,11 +137,6 @@ func (l Log) DeepCopy() Log { } // LogEntry represents all information captured for a log entry. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type LogEntry struct { // Timestamp stores the time when the log entry was created. Timestamp time.Time @@ -214,38 +169,18 @@ type LogEntry struct { // LogType determines whether a log entry was created with an Error or Info // call. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type LogType string const ( // LogError is the special value used for Error log entries. - // - // Experimental - // - // Notice: This value is EXPERIMENTAL and may be changed or removed in - // a later release. LogError = LogType("ERROR") // LogInfo is the special value used for Info log entries. - // - // Experimental - // - // Notice: This value is EXPERIMENTAL and may be changed or removed in - // a later release. LogInfo = LogType("INFO") ) // Underlier is implemented by the LogSink of this logger. It provides access // to additional APIs that are normally hidden behind the Logger API. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type Underlier interface { // GetUnderlying returns the testing instance that logging goes to. // It returns nil when the test has completed already. diff --git a/test/output.go b/test/output.go index e3bc181ba..ce769dc52 100644 --- a/test/output.go +++ b/test/output.go @@ -15,11 +15,6 @@ limitations under the License. */ // Package test contains a reusable unit test for logging output and behavior. -// -// # Experimental -// -// Notice: This package is EXPERIMENTAL and may be changed or removed in a -// later release. package test import ( @@ -48,11 +43,6 @@ import ( // // The returned flag set has the klog flags registered. It can // be used to make further changes to the klog configuration. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func InitKlog(tb testing.TB) *flag.FlagSet { state := klog.CaptureState() tb.Cleanup(state.Restore) @@ -77,11 +67,6 @@ func InitKlog(tb testing.TB) *flag.FlagSet { } // OutputConfig contains optional settings for Output. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type OutputConfig struct { // NewLogger is called to create a new logger. If nil, output via klog // is tested. Support for -vmodule is optional. ClearLogger is called @@ -553,12 +538,6 @@ var _, _, printWithKlogLine, _ = runtime.Caller(0) // anchor for finding the lin // // Loggers will be tested with direct calls to Info or // as backend for klog. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. The test cases and thus the expected output also may -// change. func Output(t *testing.T, config OutputConfig) { for n, test := range tests { t.Run(n, func(t *testing.T) { @@ -879,12 +858,6 @@ func Output(t *testing.T, config OutputConfig) { // // Loggers will be tested with direct calls to Info or // as backend for klog. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. The test cases and thus the expected output also may -// change. func Benchmark(b *testing.B, config OutputConfig) { for n, test := range tests { b.Run(n, func(b *testing.B) { diff --git a/test/zapr.go b/test/zapr.go index 6c7e809fb..dcd357554 100644 --- a/test/zapr.go +++ b/test/zapr.go @@ -18,11 +18,6 @@ package test // ZaprOutputMappingDirect provides a mapping from klog output to the // corresponding zapr output when zapr is called directly. -// -// # Experimental -// -// Notice: This package is EXPERIMENTAL and may be changed or removed in a -// later release. func ZaprOutputMappingDirect() map[string]string { return map[string]string{ `I output.go:] "test" akey="<&>" @@ -282,11 +277,6 @@ I output.go:] "odd WithValues" keyWithoutValue="(MISSING)" // - zap drops keys with missing values, here we get "(MISSING)". // - zap does not de-duplicate key/value pairs, here klog does that // for it. -// -// # Experimental -// -// Notice: This package is EXPERIMENTAL and may be changed or removed in a -// later release. func ZaprOutputMappingIndirect() map[string]string { mapping := ZaprOutputMappingDirect() diff --git a/textlogger/options.go b/textlogger/options.go index db4cbebdc..14cfa8088 100644 --- a/textlogger/options.go +++ b/textlogger/options.go @@ -30,11 +30,6 @@ import ( // bind command line flags to the instance before passing it to NewTestContext. // // Must be constructed with NewConfig. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type Config struct { vstate *verbosity.VState co configOptions @@ -55,11 +50,6 @@ func (c *Config) VModule() flag.Value { } // ConfigOption implements functional parameters for NewConfig. -// -// # Experimental -// -// Notice: This type is EXPERIMENTAL and may be changed or removed in a -// later release. type ConfigOption func(co *configOptions) type configOptions struct { @@ -79,11 +69,6 @@ func VerbosityFlagName(name string) ConfigOption { // VModulFlagName overrides the default -vmodule for the per-module // verbosity levels. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func VModuleFlagName(name string) ConfigOption { return func(co *configOptions) { co.vmoduleFlagName = name @@ -93,11 +78,6 @@ func VModuleFlagName(name string) ConfigOption { // Verbosity overrides the default verbosity level of 0. // See https://github.com/kubernetes/community/blob/9406b4352fe2d5810cb21cc3cb059ce5886de157/contributors/devel/sig-instrumentation/logging.md#logging-conventions // for log level conventions in Kubernetes. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func Verbosity(level int) ConfigOption { return func(co *configOptions) { co.verbosityDefault = level @@ -105,11 +85,6 @@ func Verbosity(level int) ConfigOption { } // Output overrides stderr as the output stream. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func Output(output io.Writer) ConfigOption { return func(co *configOptions) { co.output = output @@ -118,11 +93,6 @@ func Output(output io.Writer) ConfigOption { // NewConfig returns a configuration with recommended defaults and optional // modifications. Command line flags are not bound to any FlagSet yet. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func NewConfig(opts ...ConfigOption) *Config { c := &Config{ vstate: verbosity.New(), @@ -142,11 +112,6 @@ func NewConfig(opts ...ConfigOption) *Config { } // AddFlags registers the command line flags that control the configuration. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. func (c *Config) AddFlags(fs *flag.FlagSet) { fs.Var(c.Verbosity(), c.co.verbosityFlagName, "number for the log level verbosity of the testing logger") fs.Var(c.VModule(), c.co.vmoduleFlagName, "comma-separated list of pattern=N log level settings for files matching the patterns") diff --git a/textlogger/textlogger.go b/textlogger/textlogger.go index 3c0e079ad..90b265003 100644 --- a/textlogger/textlogger.go +++ b/textlogger/textlogger.go @@ -17,11 +17,6 @@ limitations under the License. // Package textlogger contains an implementation of the logr interface // which is producing the exact same output as klog. -// -// # Experimental -// -// Notice: This package is EXPERIMENTAL and may be changed or removed in a -// later release. package textlogger import ( @@ -40,11 +35,6 @@ import ( var ( // TimeNow is used to retrieve the current time. May be changed for testing. - // - // Experimental - // - // Notice: This variable is EXPERIMENTAL and may be changed or removed in a - // later release. TimeNow = time.Now ) @@ -52,11 +42,6 @@ var ( // // Verbosity can be modified at any time through the Config.V and // Config.VModule API. -// -// # Experimental -// -// Notice: This function is EXPERIMENTAL and may be changed or removed in a -// later release. The behavior of the returned Logger may change. func NewLogger(c *Config) logr.Logger { return logr.New(&tlogger{ prefix: "",