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.

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

promote contextual logging APIs to stable #311

Merged
merged 1 commit into from
Mar 20, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,15 @@ Historical context is available here:
Semantic versioning is used in this repository. It contains several Go modules
with different levels of stability:
- `k8s.io/klog/v2` - stable API, `vX.Y.Z` tags
- `k8s.io/tools` - no stable API yet (may change eventually), `tools/v0.Y.Z` tags
- `k8s.io/hack/tools` - no stable API yet (may change eventually or get moved to separate repo), `hack/tools/v0.Y.Z` tags
- `examples` - no stable API, no tags, no intention to ever stabilize

Exempt from the API stability guarantee are items (packages, functions, etc.)
which are marked explicitly as `EXPERIMENTAL` in their docs comment. Those
may still change in incompatible ways or get removed entirely.
may still change in incompatible ways or get removed entirely. This can only
be used for code that is used in tests to avoid situations where non-test
code from two different Kubernetes dependencies depends on incompatible
releases of klog because an experimental API was changed.

----

Expand Down
55 changes: 0 additions & 55 deletions contextual.go
Original file line number Diff line number Diff line change
Expand Up @@ -84,11 +84,6 @@ func SetLogger(logger logr.Logger) {
// Supporting direct calls is recommended because it avoids the overhead of
// routing log entries through klogr into klog and then into the actual Logger
// backend.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func SetLoggerWithOptions(logger logr.Logger, opts ...LoggerOption) {
globalLogger = &logger
globalLoggerOptions = loggerOptions{}
Expand All @@ -100,23 +95,13 @@ func SetLoggerWithOptions(logger logr.Logger, opts ...LoggerOption) {
// ContextualLogger determines whether the logger passed to
// SetLoggerWithOptions may also get called directly. Such a logger cannot rely
// on verbosity checking in klog.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func ContextualLogger(enabled bool) LoggerOption {
return func(o *loggerOptions) {
o.contextualLogger = enabled
}
}

// FlushLogger provides a callback for flushing data buffered by the logger.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func FlushLogger(flush func()) LoggerOption {
return func(o *loggerOptions) {
o.flush = flush
Expand All @@ -125,11 +110,6 @@ func FlushLogger(flush func()) LoggerOption {

// LoggerOption implements the functional parameter paradigm for
// SetLoggerWithOptions.
//
// Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type LoggerOption func(o *loggerOptions)

type loggerOptions struct {
Expand Down Expand Up @@ -164,23 +144,13 @@ func ClearLogger() {
// to avoid the additional overhead for contextual logging.
//
// This must be called during initialization before goroutines are started.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func EnableContextualLogging(enabled bool) {
contextualLoggingEnabled = enabled
}

// FromContext retrieves a logger set by the caller or, if not set,
// falls back to the program's global logger (a Logger instance or klog
// itself).
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func FromContext(ctx context.Context) Logger {
if contextualLoggingEnabled {
if logger, err := logr.FromContext(ctx); err == nil {
Expand All @@ -194,11 +164,6 @@ func FromContext(ctx context.Context) Logger {
// TODO can be used as a last resort by code that has no means of
// receiving a logger from its caller. FromContext or an explicit logger
// parameter should be used instead.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func TODO() Logger {
return Background()
}
Expand All @@ -207,11 +172,6 @@ func TODO() Logger {
// that logger was initialized by the program and not by code that should
// better receive a logger via its parameters. TODO can be used as a temporary
// solution for such code.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func Background() Logger {
if globalLoggerOptions.contextualLogger {
// Is non-nil because globalLoggerOptions.contextualLogger is
Expand All @@ -224,11 +184,6 @@ func Background() Logger {

// LoggerWithValues returns logger.WithValues(...kv) when
// contextual logging is enabled, otherwise the logger.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func LoggerWithValues(logger Logger, kv ...interface{}) Logger {
if contextualLoggingEnabled {
return logger.WithValues(kv...)
Expand All @@ -238,11 +193,6 @@ func LoggerWithValues(logger Logger, kv ...interface{}) Logger {

// LoggerWithName returns logger.WithName(name) when contextual logging is
// enabled, otherwise the logger.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func LoggerWithName(logger Logger, name string) Logger {
if contextualLoggingEnabled {
return logger.WithName(name)
Expand All @@ -252,11 +202,6 @@ func LoggerWithName(logger Logger, name string) Logger {

// NewContext returns logr.NewContext(ctx, logger) when
// contextual logging is enabled, otherwise ctx.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func NewContext(ctx context.Context, logger Logger) context.Context {
if contextualLoggingEnabled {
return logr.NewContext(ctx, logger)
Expand Down
20 changes: 0 additions & 20 deletions imports.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,35 +24,15 @@ import (
// without directly importing it.

// Logger in this package is exactly the same as logr.Logger.
//
// Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type Logger = logr.Logger

// LogSink in this package is exactly the same as logr.LogSink.
//
// Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type LogSink = logr.LogSink

// Runtimeinfo in this package is exactly the same as logr.RuntimeInfo.
//
// Experimental
//
// Notice: This type is EXPERIMENTAL and may be changed or removed in a
// later release.
type RuntimeInfo = logr.RuntimeInfo

var (
// New is an alias for logr.New.
//
// Experimental
//
// Notice: This variable is EXPERIMENTAL and may be changed or removed in a
// later release.
New = logr.New
)
5 changes: 0 additions & 5 deletions klogr.go
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,6 @@ import (
// NewKlogr returns a logger that is functionally identical to
// klogr.NewWithOptions(klogr.FormatKlog), i.e. it passes through to klog. The
// difference is that it uses a simpler implementation.
//
// Experimental
//
// Notice: This function is EXPERIMENTAL and may be changed or removed in a
// later release.
func NewKlogr() Logger {
return New(&klogger{})
}
Expand Down