diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 11aecceb..cca0121f 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -4,7 +4,7 @@ jobs: test: strategy: matrix: - go-version: [1.15, 1.16, 1.17, 1.18] + go-version: [1.17, 1.18, 1.19] platform: [ubuntu-latest, macos-latest, windows-latest] runs-on: ${{ matrix.platform }} steps: diff --git a/contextual.go b/contextual.go index 65ac479a..2428963c 100644 --- a/contextual.go +++ b/contextual.go @@ -47,8 +47,9 @@ var ( // If set, all log lines will be suppressed from the regular output, and // redirected to the logr implementation. // Use as: -// ... -// klog.SetLogger(zapr.NewLogger(zapLog)) +// +// ... +// klog.SetLogger(zapr.NewLogger(zapLog)) // // To remove a backing logr implemention, use ClearLogger. Setting an // empty logger with SetLogger(logr.Logger{}) does not work. diff --git a/klog.go b/klog.go index 652fadcd..628117e6 100644 --- a/klog.go +++ b/klog.go @@ -39,39 +39,38 @@ // This package provides several flags that modify this behavior. // As a result, flag.Parse must be called before any logging is done. // -// -logtostderr=true -// Logs are written to standard error instead of to files. -// This shortcuts most of the usual output routing: -// -alsologtostderr, -stderrthreshold and -log_dir have no -// effect and output redirection at runtime with SetOutput is -// ignored. -// -alsologtostderr=false -// Logs are written to standard error as well as to files. -// -stderrthreshold=ERROR -// Log events at or above this severity are logged to standard -// error as well as to files. -// -log_dir="" -// Log files will be written to this directory instead of the -// default temporary directory. +// -logtostderr=true +// Logs are written to standard error instead of to files. +// This shortcuts most of the usual output routing: +// -alsologtostderr, -stderrthreshold and -log_dir have no +// effect and output redirection at runtime with SetOutput is +// ignored. +// -alsologtostderr=false +// Logs are written to standard error as well as to files. +// -stderrthreshold=ERROR +// Log events at or above this severity are logged to standard +// error as well as to files. +// -log_dir="" +// Log files will be written to this directory instead of the +// default temporary directory. // -// Other flags provide aids to debugging. -// -// -log_backtrace_at="" -// When set to a file and line number holding a logging statement, -// such as -// -log_backtrace_at=gopherflakes.go:234 -// a stack trace will be written to the Info log whenever execution -// hits that statement. (Unlike with -vmodule, the ".go" must be -// present.) -// -v=0 -// Enable V-leveled logging at the specified level. -// -vmodule="" -// The syntax of the argument is a comma-separated list of pattern=N, -// where pattern is a literal file name (minus the ".go" suffix) or -// "glob" pattern and N is a V level. For instance, -// -vmodule=gopher*=3 -// sets the V level to 3 in all Go files whose names begin "gopher". +// Other flags provide aids to debugging. // +// -log_backtrace_at="" +// When set to a file and line number holding a logging statement, +// such as +// -log_backtrace_at=gopherflakes.go:234 +// a stack trace will be written to the Info log whenever execution +// hits that statement. (Unlike with -vmodule, the ".go" must be +// present.) +// -v=0 +// Enable V-leveled logging at the specified level. +// -vmodule="" +// The syntax of the argument is a comma-separated list of pattern=N, +// where pattern is a literal file name (minus the ".go" suffix) or +// "glob" pattern and N is a V level. For instance, +// -vmodule=gopher*=3 +// sets the V level to 3 in all Go files whose names begin "gopher". package klog import ( @@ -633,8 +632,11 @@ It returns a buffer containing the formatted header and the user's file and line The depth specifies how many stack frames above lives the source line to be identified in the log message. Log lines have this form: + Lmmdd hh:mm:ss.uuuuuu threadid file:line] msg... + where the fields are defined as follows: + L A single character, representing the log level (eg 'I' for INFO) mm The month (zero padded; ie May is '05') dd The day (zero padded) @@ -1298,9 +1300,13 @@ func newVerbose(level Level, b bool) Verbose { // The returned value is a struct of type Verbose, which implements Info, Infoln // and Infof. These methods will write to the Info log if called. // Thus, one may write either +// // if klog.V(2).Enabled() { klog.Info("log this") } +// // or +// // klog.V(2).Info("log this") +// // The second form is shorter but the first is cheaper if logging is off because it does // not evaluate its arguments. // @@ -1582,10 +1588,10 @@ func ErrorSDepth(depth int, err error, msg string, keysAndValues ...interface{}) // // Callers who want more control over handling of fatal events may instead use a // combination of different functions: -// - some info or error logging function, optionally with a stack trace -// value generated by github.com/go-logr/lib/dbg.Backtrace -// - Flush to flush pending log data -// - panic, os.Exit or returning to the caller with an error +// - some info or error logging function, optionally with a stack trace +// value generated by github.com/go-logr/lib/dbg.Backtrace +// - Flush to flush pending log data +// - panic, os.Exit or returning to the caller with an error // // Arguments are handled in the manner of fmt.Print; a newline is appended if missing. func Fatal(args ...interface{}) { diff --git a/ktesting/init/init.go b/ktesting/init/init.go index c1fa145a..7eb4dc67 100644 --- a/ktesting/init/init.go +++ b/ktesting/init/init.go @@ -18,7 +18,7 @@ limitations under the License. // the flag.CommandLine. This is done during initialization, so merely // importing it is enough. // -// Experimental +// # Experimental // // Notice: This package is EXPERIMENTAL and may be changed or removed in a // later release. diff --git a/ktesting/options.go b/ktesting/options.go index 8cb13c40..743b51eb 100644 --- a/ktesting/options.go +++ b/ktesting/options.go @@ -29,7 +29,7 @@ import ( // // Must be constructed with NewConfig. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -40,7 +40,7 @@ type Config struct { // ConfigOption implements functional parameters for NewConfig. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -54,7 +54,7 @@ type configOptions struct { // VerbosityFlagName overrides the default -testing.v for the verbosity level. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -67,7 +67,7 @@ func VerbosityFlagName(name string) ConfigOption { // VModulFlagName overrides the default -testing.vmodule for the per-module // verbosity levels. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -84,7 +84,7 @@ func VModuleFlagName(name string) ConfigOption { // 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 +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -97,7 +97,7 @@ func Verbosity(level int) ConfigOption { // NewConfig returns a configuration with recommended defaults and optional // modifications. Command line flags are not bound to any FlagSet yet. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -120,7 +120,7 @@ func NewConfig(opts ...ConfigOption) *Config { // AddFlags registers the command line flags that control the configuration. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. diff --git a/ktesting/setup.go b/ktesting/setup.go index d3029ae9..16b218ec 100644 --- a/ktesting/setup.go +++ b/ktesting/setup.go @@ -25,7 +25,7 @@ import ( // DefaultConfig is the global default logging configuration for a unit // test. It is used by NewTestContext and k8s.io/klogr/testing/init. // -// Experimental +// # Experimental // // Notice: This variable is EXPERIMENTAL and may be changed or removed in a // later release. @@ -36,7 +36,7 @@ var DefaultConfig = NewConfig() // 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 +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. diff --git a/ktesting/testinglogger.go b/ktesting/testinglogger.go index b3272845..67bbd857 100644 --- a/ktesting/testinglogger.go +++ b/ktesting/testinglogger.go @@ -25,17 +25,17 @@ limitations under the License. // access to that data, cast the LogSink into the Underlier type and retrieve // it: // -// logger := ktesting.NewLogger(...) -// if testingLogger, ok := logger.GetSink().(ktesting.Underlier); ok { -// t := testingLogger.GetUnderlying() -// buffer := testingLogger.GetBuffer() -// text := buffer.String() -// log := buffer.Data() +// logger := ktesting.NewLogger(...) +// if testingLogger, ok := logger.GetSink().(ktesting.Underlier); ok { +// t := testingLogger.GetUnderlying() +// buffer := testingLogger.GetBuffer() +// text := buffer.String() +// log := buffer.Data() // // Serialization of the structured log parameters is done in the same way // as for klog.InfoS. // -// Experimental +// # Experimental // // Notice: This package is EXPERIMENTAL and may be changed or removed in a // later release. @@ -57,7 +57,7 @@ import ( // TL is the relevant subset of testing.TB. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -69,7 +69,7 @@ type TL interface { // NopTL implements TL with empty stubs. It can be used when only capturing // output in memory is relevant. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -88,7 +88,7 @@ var _ TL = NopTL{} // that output will be printed via the global klog logger with // ` leaked goroutine` as prefix. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -117,7 +117,7 @@ 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 +// # Experimental // // Notice: This interface is EXPERIMENTAL and may be changed or removed in a // later release. @@ -132,7 +132,7 @@ type Buffer interface { // Log contains log entries in the order in which they were generated. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -141,7 +141,7 @@ type Log []LogEntry // DeepCopy returns a copy of the log. The error instance and key/value // pairs remain shared. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -153,7 +153,7 @@ func (l Log) DeepCopy() Log { // LogEntry represents all information captured for a log entry. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -190,7 +190,7 @@ type LogEntry struct { // LogType determines whether a log entry was created with an Error or Info // call. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -217,7 +217,7 @@ const ( // Underlier is implemented by the LogSink of this logger. It provides access // to additional APIs that are normally hidden behind the Logger API. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. diff --git a/test/output.go b/test/output.go index 775571f2..5b80ebcd 100644 --- a/test/output.go +++ b/test/output.go @@ -16,7 +16,7 @@ limitations under the License. // Package test contains a reusable unit test for logging output and behavior. // -// Experimental +// # Experimental // // Notice: This package is EXPERIMENTAL and may be changed or removed in a // later release. @@ -44,7 +44,7 @@ import ( // InitKlog must be called once in an init function of a test package to // configure klog for testing with Output. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -61,7 +61,7 @@ func InitKlog() { // OutputConfig contains optional settings for Output. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -103,7 +103,7 @@ type OutputConfig struct { // Loggers will be tested with direct calls to Info or // as backend for klog. // -// Experimental +// # 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 diff --git a/test/zapr.go b/test/zapr.go index 427d1f78..9f6cd8b4 100644 --- a/test/zapr.go +++ b/test/zapr.go @@ -19,7 +19,7 @@ package test // ZaprOutputMappingDirect provides a mapping from klog output to the // corresponding zapr output when zapr is called directly. // -// Experimental +// # Experimental // // Notice: This package is EXPERIMENTAL and may be changed or removed in a // later release. @@ -241,18 +241,18 @@ I output.go:] "odd WithValues" keyWithoutValue="(MISSING)" // klog. // // This is different from ZaprOutputMappingDirect because: -// - WithName gets added to the message by Output. -// - zap uses . as separator instead of / between WithName values, -// here we get slashes because Output concatenates these values. -// - WithValues are added to the normal key/value parameters by -// Output, which puts them after "v". -// - Output does that without emitting the warning that we get -// from zapr. -// - zap drops keys with missing values, here we get "(MISSING)". -// - zap does not de-duplicate key/value pairs, here klog does that -// for it. +// - WithName gets added to the message by Output. +// - zap uses . as separator instead of / between WithName values, +// here we get slashes because Output concatenates these values. +// - WithValues are added to the normal key/value parameters by +// Output, which puts them after "v". +// - Output does that without emitting the warning that we get +// from zapr. +// - 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 +// # Experimental // // Notice: This package is EXPERIMENTAL and may be changed or removed in a // later release. diff --git a/textlogger/options.go b/textlogger/options.go index 28188ddf..5803ccec 100644 --- a/textlogger/options.go +++ b/textlogger/options.go @@ -31,7 +31,7 @@ import ( // // Must be constructed with NewConfig. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -42,7 +42,7 @@ type Config struct { // ConfigOption implements functional parameters for NewConfig. // -// Experimental +// # Experimental // // Notice: This type is EXPERIMENTAL and may be changed or removed in a // later release. @@ -66,7 +66,7 @@ func VerbosityFlagName(name string) ConfigOption { // VModulFlagName overrides the default -vmodule for the per-module // verbosity levels. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -80,7 +80,7 @@ func VModuleFlagName(name string) ConfigOption { // See https://github.com/kubernetes/community/blob/9406b4352fe2d5810cb21cc3cb059ce5886de157/contributors/devel/sig-instrumentation/logging.md#logging-conventions // for log level conventions in Kubernetes. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -92,7 +92,7 @@ func Verbosity(level int) ConfigOption { // Output overrides stderr as the output stream. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -105,7 +105,7 @@ 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 +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. @@ -129,7 +129,7 @@ func NewConfig(opts ...ConfigOption) *Config { // AddFlags registers the command line flags that control the configuration. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. diff --git a/textlogger/textlogger.go b/textlogger/textlogger.go index 17c7584f..17706d6d 100644 --- a/textlogger/textlogger.go +++ b/textlogger/textlogger.go @@ -18,7 +18,7 @@ limitations under the License. // Package textlogger contains an implementation of the logr interface // which is producing the exact same output as klog. // -// Experimental +// # Experimental // // Notice: This package is EXPERIMENTAL and may be changed or removed in a // later release. @@ -50,7 +50,7 @@ var ( // NewLogger constructs a new logger. // -// Experimental +// # Experimental // // Notice: This function is EXPERIMENTAL and may be changed or removed in a // later release. The behavior of the returned Logger may change.