v1

package
v0.29.0-alpha.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 25, 2023 License: Apache-2.0 Imports: 24 Imported by: 211

Documentation

Overview

The LoggingAlphaOptions and LoggingBetaOptions feature gates control whether these unstable features can get enabled. This can be used to ensure that command invocations do not accidentally rely on unstable features.

Index

Constants

View Source 
const (
	// owner: @pohly
	// kep: https://kep.k8s.io/3077
	// alpha: v1.24
	//
	// Enables looking up a logger from a context.Context instead of using
	// the global fallback logger and manipulating the logger that is
	// used by a call chain.
	ContextualLogging featuregate.Feature = "ContextualLogging"

	// Allow fine-tuning of experimental, alpha-quality logging options.
	//
	// Per https://groups.google.com/g/kubernetes-sig-architecture/c/Nxsc7pfe5rw/m/vF2djJh0BAAJ
	// we want to avoid a proliferation of feature gates. This feature gate:
	// - will guard *a group* of logging options whose quality level is alpha.
	// - will never graduate to beta or stable.
	LoggingAlphaOptions featuregate.Feature = "LoggingAlphaOptions"

	// Allow fine-tuning of experimental, beta-quality logging options.
	//
	// Per https://groups.google.com/g/kubernetes-sig-architecture/c/Nxsc7pfe5rw/m/vF2djJh0BAAJ
	// we want to avoid a proliferation of feature gates. This feature gate:
	// - will guard *a group* of logging options whose quality level is beta.
	// - is thus *introduced* as beta
	// - will never graduate to stable.
	LoggingBetaOptions featuregate.Feature = "LoggingBetaOptions"

	// Stable logging options. Always enabled.
	LoggingStableOptions featuregate.Feature = "LoggingStableOptions"
)
View Source 
const (
	// DefaultLogFormat is the traditional klog output format.
	DefaultLogFormat = "text"

	// JSONLogFormat emits each log message as a JSON struct.
	JSONLogFormat = "json"
)

Supported output formats.

View Source 
const (
	// LogFlushFreqDefault is the default for the corresponding command line
	// parameter.
	LogFlushFreqDefault = 5 * time.Second
)
View Source 
const (
	// LogFlushFreqFlagName is the name of the command line parameter.
	// Depending on how flags get added, it is either a stand-alone
	// value (logs.AddFlags) or part of LoggingConfiguration.
	LogFlushFreqFlagName = "log-flush-frequency"
)

Variables

View Source 
var ReapplyHandling = ReapplyHandlingError

Applying configurations multiple times is not safe unless it's guaranteed that there are no goroutines which might call logging functions. The default for ValidateAndApply and ValidateAndApplyWithOptions is to return an error when called more than once. Binaries and unit tests can override that behavior.

Functions

func AddFeatureGates 

func AddFeatureGates(mutableFeatureGate featuregate.MutableFeatureGate) error

AddFeatureGates adds all feature gates used by this package.

func AddFlags 

func AddFlags(c *LoggingConfiguration, fs *pflag.FlagSet)

AddFlags adds command line flags for the configuration.

func AddGoFlags added in v0.27.0 

func AddGoFlags(c *LoggingConfiguration, fs *flag.FlagSet)

AddGoFlags is a variant of AddFlags for a standard FlagSet.

func RegisterLogFormat 

func RegisterLogFormat(name string, factory LogFormatFactory, feature featuregate.Feature) error

RegisterLogFormat registers support for a new logging format. This must be called before using any of the methods in LoggingConfiguration. The feature must be one of those defined in this package (typically LoggingAlphaOptions, LoggingBetaOptions or LoggingStableOptions).

func ResetForTest added in v0.28.0 

func ResetForTest(featureGate featuregate.FeatureGate) error

ResetForTest restores the default settings. This is not thread-safe and should only be used when there are no goroutines running. The intended users are unit tests in other packages.

func SetRecommendedLoggingConfiguration 

func SetRecommendedLoggingConfiguration(c *LoggingConfiguration)

SetRecommendedLoggingConfiguration sets the default logging configuration for fields that are unset.

Consumers who embed LoggingConfiguration in their own configuration structs may set custom defaults and then should call this function to add the global defaults.

func VModuleConfigurationPflag 

func VModuleConfigurationPflag(value *VModuleConfiguration) pflag.Value

VModuleConfigurationPflag implements the pflag.Value interface for a VModuleConfiguration. The value pointer must not be nil.

func Validate 

func Validate(c *LoggingConfiguration, featureGate featuregate.FeatureGate, fldPath *field.Path) field.ErrorList

Validate can be used to check for invalid settings without applying them. Most binaries should validate and apply the logging configuration as soon as possible via ValidateAndApply. The field path is optional: nil can be passed when the struct is not embedded in some larger struct.

func ValidateAndApply 

func ValidateAndApply(c *LoggingConfiguration, featureGate featuregate.FeatureGate) error

ValidateAndApply combines validation and application of the logging configuration. This should be invoked as early as possible because then the rest of the program startup (including validation of other options) will already run with the final logging configuration.

The optional FeatureGate controls logging features. If nil, the default for these features is used.

Logging options must be applied as early as possible during the program startup. Some changes are global and cannot be done safely when there are already goroutines running.

func ValidateAndApplyAsField 

func ValidateAndApplyAsField(c *LoggingConfiguration, featureGate featuregate.FeatureGate, fldPath *field.Path) error

ValidateAndApplyAsField is a variant of ValidateAndApply that should be used when the LoggingConfiguration is embedded in some larger configuration structure.

func ValidateAndApplyWithOptions added in v0.27.0 

func ValidateAndApplyWithOptions(c *LoggingConfiguration, options *LoggingOptions, featureGate featuregate.FeatureGate) error

ValidateAndApplyWithOptions is a variant of ValidateAndApply which accepts additional options beyond those that can be configured through the API. This is meant for testing.

Logging options must be applied as early as possible during the program startup. Some changes are global and cannot be done safely when there are already goroutines running.

func VerbosityLevelPflag 

func VerbosityLevelPflag(value *VerbosityLevel) pflag.Value

VerbosityLevelPflag implements the pflag.Value interface for a verbosity level value.

Types

type FormatOptions 

type FormatOptions struct {
	// [Alpha] JSON contains options for logging format "json".
	// Only available when the LoggingAlphaOptions feature gate is enabled.
	JSON JSONOptions `json:"json,omitempty"`
}

FormatOptions contains options for the different logging formats.

func (*FormatOptions) DeepCopy 

func (in *FormatOptions) DeepCopy() *FormatOptions

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new FormatOptions.

func (*FormatOptions) DeepCopyInto 

func (in *FormatOptions) DeepCopyInto(out *FormatOptions)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type JSONOptions 

type JSONOptions struct {
	// [Alpha] SplitStream redirects error messages to stderr while
	// info messages go to stdout, with buffering. The default is to write
	// both to stdout, without buffering. Only available when
	// the LoggingAlphaOptions feature gate is enabled.
	SplitStream bool `json:"splitStream,omitempty"`
	// [Alpha] InfoBufferSize sets the size of the info stream when
	// using split streams. The default is zero, which disables buffering.
	// Only available when the LoggingAlphaOptions feature gate is enabled.
	InfoBufferSize resource.QuantityValue `json:"infoBufferSize,omitempty"`
}

JSONOptions contains options for logging format "json".

func (*JSONOptions) DeepCopy 

func (in *JSONOptions) DeepCopy() *JSONOptions

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new JSONOptions.

func (*JSONOptions) DeepCopyInto 

func (in *JSONOptions) DeepCopyInto(out *JSONOptions)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type LogFormatFactory 

type LogFormatFactory interface {
	// Create returns a logger with the requested configuration.
	Create(c LoggingConfiguration, o LoggingOptions) (logr.Logger, RuntimeControl)
}

LogFormatFactory provides support for a certain additional, non-default log format.

type LoggingConfiguration 

type LoggingConfiguration struct {
	// Format Flag specifies the structure of log messages.
	// default value of format is `text`
	Format string `json:"format,omitempty"`
	// Maximum time between log flushes.
	// If a string, parsed as a duration (i.e. "1s")
	// If an int, the maximum number of nanoseconds (i.e. 1s = 1000000000).
	// Ignored if the selected logging backend writes log messages without buffering.
	FlushFrequency TimeOrMetaDuration `json:"flushFrequency"`
	// Verbosity is the threshold that determines which log messages are
	// logged. Default is zero which logs only the most important
	// messages. Higher values enable additional messages. Error messages
	// are always logged.
	Verbosity VerbosityLevel `json:"verbosity"`
	// VModule overrides the verbosity threshold for individual files.
	// Only supported for "text" log format.
	VModule VModuleConfiguration `json:"vmodule,omitempty"`
	// [Alpha] Options holds additional parameters that are specific
	// to the different logging formats. Only the options for the selected
	// format get used, but all of them get validated.
	// Only available when the LoggingAlphaOptions feature gate is enabled.
	Options FormatOptions `json:"options,omitempty"`
}

LoggingConfiguration contains logging options.

func NewLoggingConfiguration 

func NewLoggingConfiguration() *LoggingConfiguration

NewLoggingConfiguration returns a struct holding the default logging configuration.

func (*LoggingConfiguration) DeepCopy 

func (in *LoggingConfiguration) DeepCopy() *LoggingConfiguration

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LoggingConfiguration.

func (*LoggingConfiguration) DeepCopyInto 

func (in *LoggingConfiguration) DeepCopyInto(out *LoggingConfiguration)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type LoggingOptions added in v0.27.0 

type LoggingOptions struct {
	// ErrorStream can be used to override the os.Stderr default.
	ErrorStream io.Writer

	// InfoStream can be used to override the os.Stdout default.
	InfoStream io.Writer
}

LoggingOptions can be used with ValidateAndApplyWithOptions to override certain global defaults.

type ReapplyHandlingType added in v0.28.0 

type ReapplyHandlingType int
const (
	// ReapplyHandlingError is the default: calling ValidateAndApply or
	// ValidateAndApplyWithOptions again returns an error.
	ReapplyHandlingError ReapplyHandlingType = iota
	// ReapplyHandlingIgnoreUnchanged silently ignores any additional calls of
	// ValidateAndApply or ValidateAndApplyWithOptions if the configuration
	// is unchanged, otherwise they return an error.
	ReapplyHandlingIgnoreUnchanged
)

type RuntimeControl added in v0.27.0 

type RuntimeControl struct {
	// Flush ensures that all in-memory data is written.
	// May be nil.
	Flush func()

	// SetVerbosityLevel changes the level for all Logger instances
	// derived from the initial one. May be nil.
	//
	// The parameter is intentionally a plain uint32 instead of
	// VerbosityLevel to enable implementations that don't need to import
	// the API (helps avoid circular dependencies).
	SetVerbosityLevel func(v uint32) error
}

RuntimeControl provides operations that aren't available through the normal Logger or LogSink API.

type TimeOrMetaDuration added in v0.28.0 

type TimeOrMetaDuration struct {
	// Duration holds the duration
	Duration metav1.Duration
	// SerializeAsString controls whether the value is serialized as a string or an integer
	SerializeAsString bool `json:"-"`
}

TimeOrMetaDuration is present only for backwards compatibility for the flushFrequency field, and new fields should use metav1.Duration.

func (*TimeOrMetaDuration) DeepCopy added in v0.28.0 

func (in *TimeOrMetaDuration) DeepCopy() *TimeOrMetaDuration

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new TimeOrMetaDuration.

func (*TimeOrMetaDuration) DeepCopyInto added in v0.28.0 

func (in *TimeOrMetaDuration) DeepCopyInto(out *TimeOrMetaDuration)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

func (TimeOrMetaDuration) MarshalJSON added in v0.28.0 

func (t TimeOrMetaDuration) MarshalJSON() ([]byte, error)

func (*TimeOrMetaDuration) UnmarshalJSON added in v0.28.0 

func (t *TimeOrMetaDuration) UnmarshalJSON(b []byte) error

type VModuleConfiguration 

type VModuleConfiguration []VModuleItem

VModuleConfiguration is a collection of individual file names or patterns and the corresponding verbosity threshold.

func (VModuleConfiguration) DeepCopy 

func (in VModuleConfiguration) DeepCopy() VModuleConfiguration

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new VModuleConfiguration.

func (VModuleConfiguration) DeepCopyInto 

func (in VModuleConfiguration) DeepCopyInto(out *VModuleConfiguration)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type VModuleItem 

type VModuleItem struct {
	// FilePattern is a base file name (i.e. minus the ".go" suffix and
	// directory) or a "glob" pattern for such a name. It must not contain
	// comma and equal signs because those are separators for the
	// corresponding klog command line argument.
	FilePattern string `json:"filePattern"`
	// Verbosity is the threshold for log messages emitted inside files
	// that match the pattern.
	Verbosity VerbosityLevel `json:"verbosity"`
}

VModuleItem defines verbosity for one or more files which match a certain glob pattern.

func (*VModuleItem) DeepCopy 

func (in *VModuleItem) DeepCopy() *VModuleItem

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new VModuleItem.

func (*VModuleItem) DeepCopyInto 

func (in *VModuleItem) DeepCopyInto(out *VModuleItem)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type VerbosityLevel 

type VerbosityLevel uint32

VerbosityLevel represents a klog or logr verbosity threshold.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.