Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: clarify relationship between different features #395

Merged
merged 1 commit into from
Nov 17, 2023
+24 −5
Merged

docs: clarify relationship between different features #395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
23 changes: 20 additions & 3 deletions klog.go
View file
Open in desktop
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:
Copy link
Author

@pohly pohly Nov 16, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've checked with go install golang.org/x/pkgsite/cmd/pkgsite@latest && pkgsite that this renders okay.

//
// - 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 functions 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 off
// 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
View file
Open in desktop
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