klog

package module
v1.0.3 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2021 License: Apache-2.0 Imports: 18 Imported by: 4

README

klog

klog is a permanent fork of https://github.com/golang/glog.

Why was klog created?

The decision to create klog was one that wasn't made lightly, but it was necessary due to some drawbacks that are present in glog. Ultimately, the fork was created due to glog not being under active development; this can be seen in the glog README:

The code in this repo [...] is not itself under development

This makes us unable to solve many use cases without a fork. The factors that contributed to needing feature development are listed below:

  • glog presents a lot "gotchas" and introduces challenges in containerized environments, all of which aren't well documented.
  • glog doesn't provide an easy way to test logs, which detracts from the stability of software using it
  • A long term goal is to implement a logging interface that allows us to add context, change output format, etc.

Historical context is available here:

How to use klog

  • Replace imports for "github.com/golang/glog" with "k8s.io/klog/v2"
  • Use klog.InitFlags(nil) explicitly for initializing global flags as we no longer use init() method to register the flags
  • You can now use log_file instead of log_dir for logging to a single file (See examples/log_file/usage_log_file.go)
  • If you want to redirect everything logged using klog somewhere else (say syslog!), you can use klog.SetOutput() method and supply a io.Writer. (See examples/set_output/usage_set_output.go)
  • For more logging conventions (See Logging Conventions)

NOTE: please use the newer go versions that support semantic import versioning in modules, ideally go 1.11.4 or greater.

Coexisting with klog/v2

See this example to see how to coexist with both klog/v1 and klog/v2.

Coexisting with glog

This package can be used side by side with glog. This example shows how to initialize and synchronize flags from the global flag.CommandLine FlagSet. In addition, the example makes use of stderr as combined output by setting alsologtostderr (or logtostderr) to true.

Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the community page.

You can reach the maintainers of this project at:

Code of conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

glog

Leveled execution logs for Go.

This is an efficient pure Go implementation of leveled logs in the manner of the open source C++ package https://github.com/google/glog

By binding methods to booleans it is possible to use the log package without paying the expense of evaluating the arguments to the log. Through the -vmodule flag, the package also provides fine-grained control over logging at the file level.

The comment from glog.go introduces the ideas:

Package glog 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.

Basic examples:

	glog.Info("Prepare to repel boarders")

	glog.Fatalf("Initialization failed: %s", err)

See the documentation for the V function for an explanation
of these examples:

	if glog.V(2) {
		glog.Info("Starting transaction...")
	}

	glog.V(2).Infoln("Processed", nItems, "elements")

The repository contains an open source version of the log package used inside Google. The master copy of the source lives inside Google, not here. The code in this repo is for export only and is not itself under development. Feature requests will be ignored.

Send bug reports to golang-nuts@googlegroups.com.

Documentation

Overview

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.

Basic examples: 

klog.Info("Prepare to repel boarders")

klog.Fatalf("Initialization failed: %s", err)

See the documentation for the V function for an explanation of these examples: 

if klog.V(2) {
	klog.Info("Starting transaction...")
}

klog.V(2).Infoln("Processed", nItems, "elements")

Log output is buffered and written periodically using Flush. Programs should call Flush before exiting to guarantee all log output is written.

By default, all log statements write to standard error. This package provides several flags that modify this behavior. As a result, flag.Parse must be called before any logging is done. 

-logtostderr=true
	Logs are written to standard error instead of to files.
-alsologtostderr=false
	Logs are written to standard error as well as to files.
-stderrthreshold=ERROR
	Log events at or above this severity are logged to standard
	error as well as to files.
-log_dir=""
	Log files will be written to this directory instead of the
	default temporary directory.

Other flags provide aids to debugging.

-log_backtrace_at=""
	When set to a file and line number holding a logging statement,
	such as
		-log_backtrace_at=gopherflakes.go:234
	a stack trace will be written to the Info log whenever execution
	hits that statement. (Unlike with -vmodule, the ".go" must be
	present.)
-v=0
	Enable V-leveled logging at the specified level.
-vmodule=""
	The syntax of the argument is a comma-separated list of pattern=N,
	where pattern is a literal file name (minus the ".go" suffix) or
	"glob" pattern and N is a V level. For instance,
		-vmodule=gopher*=3
	sets the V level to 3 in all Go files whose names begin "gopher".

Index

Constants

View Source 
const (
	StdInfoColor = byte(139)
	StdErrColor  = 196
	StdWarnColor = 166
)

256 color palette mode

Variables

View Source 
var MaxSize uint64 = 1024 * 1024 * 1800

MaxSize is the maximum size of a log file in bytes.

View Source 
var Stats struct {
	Info, Warning, Error OutputStats
}

Stats tracks the number of lines of output and number of bytes per severity level. Values must be read with atomic.LoadInt64.

Functions

func AppendColorCode added in v1.0.1 

func AppendColorCode(code byte, buf []byte) int

AppendColorCode appends the console color code to the given slice. Returns how many bytes were appended. https://misc.flogisoft.com/bash/tip_colors_and_formatting

func AppendDigits added in v1.0.1 

func AppendDigits(inValue int, buf []byte) int

AppendDigits appends the base 10 value to the given buffer, returning the number of bytes written.

Pre: inValue > 0

func AppendNDigits added in v1.0.1 

func AppendNDigits(inNumDigits int, inValue int, buf []byte, inPad byte) int

AppendNDigits formats an n-digit integer to the given buffer, padding as needed, returning the number of bytes written.

Pre: len(buf) >= inNumDigits

func AppendTimestamp added in v1.0.1 

func AppendTimestamp(buf []byte) int

AppendTimestamp appends a glog/klog-style timestamp to the given slice, returning how many bytes were written.

Pre: len(buf) >= 20

func CalculateMaxSize added in v0.3.0 

func CalculateMaxSize() uint64

CalculateMaxSize returns the real max size in bytes after considering the default max size and the flag options.

func CopyStandardLogTo 

func CopyStandardLogTo(name string)

CopyStandardLogTo arranges for messages written to the Go "log" package's default logs to also appear in the Google logs for the named and lower severities. Subsequent changes to the standard log's default output location or format may break this behavior.

Valid names are "INFO", "WARNING", "ERROR", and "FATAL". If the name is not recognized, CopyStandardLogTo panics.

func Error 

func Error(args ...interface{})

Error logs to the ERROR, WARNING, and INFO logs. Arguments are handled in the manner of fmt.Print; a newline is appended if missing.

func ErrorDepth 

func ErrorDepth(depth int, args ...interface{})

ErrorDepth acts as Error but uses depth to determine which call frame to log. ErrorDepth(0, "msg") is the same as Error("msg").

func Errorf 

func Errorf(format string, args ...interface{})

Errorf logs to the ERROR, WARNING, and INFO logs. Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func Errorln 

func Errorln(args ...interface{})

Errorln logs to the ERROR, WARNING, and INFO logs. Arguments are handled in the manner of fmt.Println; a newline is always appended.

func Exit 

func Exit(args ...interface{})

Exit logs to the FATAL, ERROR, WARNING, and INFO logs, then calls os.Exit(1). Arguments are handled in the manner of fmt.Print; a newline is appended if missing.

func ExitDepth 

func ExitDepth(depth int, args ...interface{})

ExitDepth acts as Exit but uses depth to determine which call frame to log. ExitDepth(0, "msg") is the same as Exit("msg").

func Exitf 

func Exitf(format string, args ...interface{})

Exitf logs to the FATAL, ERROR, WARNING, and INFO logs, then calls os.Exit(1). Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func Exitln 

func Exitln(args ...interface{})

Exitln logs to the FATAL, ERROR, WARNING, and INFO logs, then calls os.Exit(1).

func Fatal 

func Fatal(args ...interface{})

Fatal logs to the FATAL, ERROR, WARNING, and INFO logs, including a stack trace of all running goroutines, then calls os.Exit(255). Arguments are handled in the manner of fmt.Print; a newline is appended if missing.

func FatalDepth 

func FatalDepth(depth int, args ...interface{})

FatalDepth acts as Fatal but uses depth to determine which call frame to log. FatalDepth(0, "msg") is the same as Fatal("msg").

func Fatalf 

func Fatalf(format string, args ...interface{})

Fatalf logs to the FATAL, ERROR, WARNING, and INFO logs, including a stack trace of all running goroutines, then calls os.Exit(255). Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func Fatalln 

func Fatalln(args ...interface{})

Fatalln logs to the FATAL, ERROR, WARNING, and INFO logs, including a stack trace of all running goroutines, then calls os.Exit(255). Arguments are handled in the manner of fmt.Println; a newline is always appended.

func Flush 

func Flush()

Flush flushes all pending log I/O.

func Info 

func Info(args ...interface{})

Info logs to the INFO log. Arguments are handled in the manner of fmt.Print; a newline is appended if missing.

func InfoDepth 

func InfoDepth(depth int, args ...interface{})

InfoDepth acts as Info but uses depth to determine which call frame to log. InfoDepth(0, "msg") is the same as Info("msg").

func Infof 

func Infof(format string, args ...interface{})

Infof logs to the INFO log. Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func Infoln 

func Infoln(args ...interface{})

Infoln logs to the INFO log. Arguments are handled in the manner of fmt.Println; a newline is always appended.

func InitFlags 

func InitFlags(flagset *flag.FlagSet)

InitFlags is for explicitly initializing the flags.

func LogToStderr added in v1.0.1 

func LogToStderr(stderr bool)

LogToStderr sets whether to log exclusively to stderr, bypassing outputs

func SetFormatter added in v1.0.1 

func SetFormatter(formatter Formatter)

SetFormatter sets the global/default formatter.

By default, the formatter is set to nil, meaning the historcal glog/klog formatter is used.

func SetLogger added in v1.0.1 

func SetLogger(logr logr.Logger)

SetLogger will set the backing logr implementation for klog. If set, all log lines will be suppressed from the regular Output, and redirected to the logr implementation. All log lines include the 'severity', 'file' and 'line' values attached as structured logging values. Use as: 

...
klog.SetLogger(zapr.NewLogger(zapLog))

func SetOutput 

func SetOutput(w io.Writer)

SetOutput sets the output destination for all severities

func SetOutputBySeverity 

func SetOutputBySeverity(name string, w io.Writer)

SetOutputBySeverity sets the output destination for specific severity

func Warning 

func Warning(args ...interface{})

Warning logs to the WARNING and INFO logs. Arguments are handled in the manner of fmt.Print; a newline is appended if missing.

func WarningDepth 

func WarningDepth(depth int, args ...interface{})

WarningDepth acts as Warning but uses depth to determine which call frame to log. WarningDepth(0, "msg") is the same as Warning("msg").

func Warningf 

func Warningf(format string, args ...interface{})

Warningf logs to the WARNING and INFO logs. Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func Warningln 

func Warningln(args ...interface{})

Warningln logs to the WARNING and INFO logs. Arguments are handled in the manner of fmt.Println; a newline is always appended.

Types

type FmtConstWidth added in v1.0.1 

type FmtConstWidth struct {
	// FileNameCharWidth is the number of chars to use from the given file name.
	// Filenames shorter than this are padded with spaces.
	// If 0, file names are not printed.
	FileNameCharWidth int

	// If set, color codes will be inserted
	UseColor bool
}

FmtConstWidth is a basic formatter that makes reasonable attempts to make the header length a constant width, improving readability. It also can insert console color codes so each severity level is a different color.

func (*FmtConstWidth) FormatHeader added in v1.0.1 

func (f *FmtConstWidth) FormatHeader(sevChar byte, file string, line int, buf *bytes.Buffer)

FormatHeader -- see interface Formatter

type Formatter added in v1.0.1 

type Formatter interface {

	// FormatHeader writes a formatted header to ioBuf.
	// This function is presumed to be THREADSAFE.
	FormatHeader(severityChar byte, fileName string, lineNum int, ioBuf *bytes.Buffer)
}

Formatter is a pluggable formatter for klog, allowing developers to provide custom formatting.

type KMetadata added in v1.0.1 

type KMetadata interface {
	GetName() string
	GetNamespace() string
}

KMetadata is a subset of the kubernetes k8s.io/apimachinery/pkg/apis/meta/v1.Object interface this interface may expand in the future, but will always be a subset of the kubernetes k8s.io/apimachinery/pkg/apis/meta/v1.Object interface

type Level 

type Level int32

Level specifies a level of verbosity for V logs. *Level implements flag.Value; the -v flag is of type Level and should be modified only through the flag.Value interface.

func (*Level) Get 

func (l *Level) Get() interface{}

Get is part of the flag.Getter interface.

func (*Level) Set 

func (l *Level) Set(value string) error

Set is part of the flag.Value interface.

func (*Level) String 

func (l *Level) String() string

String is part of the flag.Value interface.

type ObjectRef added in v1.0.1 

type ObjectRef struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace,omitempty"`
}

ObjectRef references a kubernetes object

func KObj added in v1.0.1 

func KObj(obj KMetadata) ObjectRef

KObj returns ObjectRef from ObjectMeta

func KRef added in v1.0.1 

func KRef(namespace, name string) ObjectRef

KRef returns ObjectRef from name and namespace

func (ObjectRef) String added in v1.0.1 

func (ref ObjectRef) String() string

type OutputStats 

type OutputStats struct {
	// contains filtered or unexported fields
}

OutputStats tracks the number of output lines and bytes written.

func (*OutputStats) Bytes 

func (s *OutputStats) Bytes() int64

Bytes returns the number of bytes written.

func (*OutputStats) Lines 

func (s *OutputStats) Lines() int64

Lines returns the number of lines written.

type Verbose 

type Verbose bool

Verbose is a boolean type that implements Infof (like Printf) etc. See the documentation of V for more information.

func V 

func V(level Level) Verbose

V reports whether verbosity at the call site is at least the requested level. The returned value is a struct of type Verbose, which implements Info, Infoln and Infof. These methods will write to the Info log if called. Thus, one may write either 

if glog.V(2).Enabled() { klog.Info("log this") }

or 

klog.V(2).Info("log this")

The second form is shorter but the first is cheaper if logging is off because it does not evaluate its arguments.

Whether an individual call to V generates a log record depends on the setting of the -v and -vmodule flags; both are off by default. The V call will log if its level is less than or equal to the value of the -v flag, or alternatively if its level is less than or equal to the value of the -vmodule pattern matching the source file containing the call.

func (Verbose) Enabled added in v1.0.1 

func (v Verbose) Enabled() bool

func (Verbose) Info 

func (v Verbose) Info(args ...interface{})

Info is equivalent to the global Info function, guarded by the value of v. See the documentation of V for usage.

func (Verbose) Infof 

func (v Verbose) Infof(format string, args ...interface{})

Infof is equivalent to the global Infof function, guarded by the value of v. See the documentation of V for usage.

func (Verbose) Infoln 

func (v Verbose) Infoln(args ...interface{})

Infoln is equivalent to the global Infoln function, guarded by the value of v. See the documentation of V for usage.

Source Files

View all Source files

Directories

Path Synopsis
integration_tests
internal
Package klogr implements github.com/go-logr/logr.Logger in terms of k8s.io/klog.
 Package klogr implements github.com/go-logr/logr.Logger in terms of k8s.io/klog.

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.