diff --git a/hack/tools/logcheck/README.md b/hack/tools/logcheck/README.md index b454237d..3eea2ddc 100644 --- a/hack/tools/logcheck/README.md +++ b/hack/tools/logcheck/README.md @@ -25,8 +25,9 @@ via a configuration file. That file contains lines in this format: `` is a comma-separated list of the names of checks that get enabled or disabled when a file name matches the regular expression. A check gets disabled when its name has `-` as prefix and enabled when there is no prefix or `+` as -prefix. All regular expressions are checked in order, so later lines can -override the previous ones. +prefix. Only checks that are mentioned explicitly are modified. All regular +expressions are checked in order, so later lines can override the previous +ones. In this example, checking for klog calls is enabled for all files under `pkg/scheduler` in the Kubernetes repo except for `scheduler.go` @@ -42,31 +43,38 @@ the next section. # Checks -## unstructured +## unstructured (enabled by default) Unstructured klog logging calls are flagged as error. -## klog +## klog (disabled by default) None of the klog logging methods may be used. This is even stricter than `unstructured`. Instead, code should retrieve a logr.Logger from klog and log through that. -## parameters +## parameters (enabled by default) -Key/value parameters for structured logging calls are checked: +This ensures that if certain logging functions are allowed and are used, those +functions are passed correct parameters. + +### all calls + +Format strings are not allowed where plain strings are expected. + +### structured logging calls + +Key/value parameters for logging calls are checked: - For each key there must be a value. - Keys must be constant strings. This also warns about code that is valid, for example code that collects key/value pairs in an `[]interface` variable before passing that on to a log call. Such valid code can use `nolint:logcheck` to disable the warning (when -invoking logcheck through golangci-lint) or the check can be disabled for the -file. - -In addition, format strings are not allowed as string parameters. +invoking logcheck through golangci-lint) or the `parameters` check can be +disabled for the file. -## with-helpers +## with-helpers (disabled by default) `logr.Logger.WithName`, `logr.Logger.WithValues` and `logr.NewContext` must not be used. The corresponding helper calls from `k8s.io/klogr` should be used diff --git a/hack/tools/logcheck/pkg/logcheck.go b/hack/tools/logcheck/pkg/logcheck.go index f4f8c741..3df749f1 100644 --- a/hack/tools/logcheck/pkg/logcheck.go +++ b/hack/tools/logcheck/pkg/logcheck.go @@ -93,7 +93,7 @@ klog methods (Info, Infof, Error, Errorf, Warningf, etc).`) return &analysis.Analyzer{ Name: "logcheck", - Doc: "Tool to check use of unstructured logging patterns.", + Doc: "Tool to check logging calls.", Run: func(pass *analysis.Pass) (interface{}, error) { return run(pass, &c) },