Skip to content

Commit

Permalink
docs: clarify relationship between different features
Browse files Browse the repository at this point in the history
With klogr being deprecated there might be some confusion whether
textlogger or klog.Background should be used instead.
  • Loading branch information
pohly committed Nov 17, 2023
1 parent e3f75b8 commit 95101f6
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 5 deletions.
23 changes: 20 additions & 3 deletions klog.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,26 @@
// See the License for the specific language governing permissions and
// limitations under the License.

// Package klog implements logging analogous to the Google-internal C++ INFO/ERROR/V setup.
// It provides functions Info, Warning, Error, Fatal, plus formatting variants such as
// Infof. It also provides V-style logging controlled by the -v and -vmodule=file=2 flags.
// Package klog contains the following functionality:
//
// - output routing as defined via command line flags ([InitFlags])
// - log formatting as text, either with a single, unstructured string ([Info], [Infof], etc.)
// or as a structured log entry with message and key/value pairs ([InfoS], etc.)
// - management of a go-logr [Logger] ([SetLogger], [Background], [TODO])
// - helper function for logging values ([Format]) and managing the state of klog ([CaptureState], [State.Restore])
// - wrappers for [logr] APIs for contextual logging where the wrappers can
// be turned into no-ops ([EnableContextualLogging], [NewContext], [FromContext],
// [LoggerWithValues], [LoggerWithName]); if the ability to turn of
// contextual logging is not needed, then go-logr can also be used directly
// - type aliases for go-logr types to simplify imports in code which uses both (e.g. [Logger])
// - [k8s.io/klog/v2/textlogger]: a logger which uses the same formatting as klog log with
// simpler output routing; beware that it comes with its own command line flags
// and does not use the ones from klog
// - [k8s.io/klog/v2/ktesting]: per-test output in Go unit tests
// - [k8s.io/klog/v2/klogr]: a deprecated, standalone [logr.Logger] on top of the main klog package;
// use [Background] instead if klog output routing is needed, [k8s.io/klog/v2/textlogger] if not
// - [k8s.io/klog/v2/examples]: demos of this functionality
// - [k8s.io/klog/v2/test]: reusable tests for [logr.Logger] implementations
//
// Basic examples:
//
Expand Down
6 changes: 4 additions & 2 deletions textlogger/textlogger.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,10 @@ See the License for the specific language governing permissions and
limitations under the License.
*/

// Package textlogger contains an implementation of the logr interface
// which is producing the exact same output as klog.
// Package textlogger contains an implementation of the logr interface which is
// producing the exact same output as klog. It does not route output through
// klog (i.e. ignores [k8s.io/klog/v2.InitFlags]). Instead, all settings must be
// configured through its own [NewConfig] and [Config.AddFlags].
package textlogger

import (
Expand Down

0 comments on commit 95101f6

Please sign in to comment.