log

package
v0.0.0-...-687b63a Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2024 License: Apache-2.0 Imports: 23 Imported by: 1,491

Documentation

Overview

Package log provides the canonical logging functionality used by Go-based Istio components.

Istio's logging subsystem is built on top of the [Zap](https://godoc.org/go.uber.org/zap) package. High performance scenarios should use the Error, Warn, Info, and Debug methods. Lower perf scenarios can use the more expensive convenience methods such as Debugf and Warnw.

The package provides direct integration with the Cobra command-line processor which makes it easy to build programs that use a consistent interface for logging. Here's an example of a simple Cobra-based program using this log package: 

		func main() {
			// get the default logging options
			options := log.DefaultOptions()

			rootCmd := &cobra.Command{
				Run: func(cmd *cobra.Command, args []string) {

					// configure the logging system
					if err := log.Configure(options); err != nil {
                     // print an error and quit
                 }

					// output some logs
					log.Info("Hello")
					log.Sync()
				},
			}

			// add logging-specific flags to the cobra command
			options.AttachCobraFlags(rootCmd)
			rootCmd.SetArgs(os.Args[1:])
			rootCmd.Execute()
		}

Once configured, this package intercepts the output of the standard golang "log" package as well as anything sent to the global zap logger (zap.L()).

Index

Constants

View Source 
const (
	DefaultScopeName  = "default"
	OverrideScopeName = "all"
)
View Source 
const (
	GrpcScopeName string = "grpc"
)

Variables

View Source 
var (
	KlogScope = RegisterScope("klog", "")
)

Functions

func Close 

func Close() error

Close implements io.Closer.

func Configure 

func Configure(options *Options) error

Configure initializes Istio's logging subsystem.

You typically call this once at process startup. Once this call returns, the logging system is ready to accept data. nolint: staticcheck

func Debug 

func Debug(fields any)

Debug outputs a message at debug level.

func DebugEnabled 

func DebugEnabled() bool

DebugEnabled returns whether output of messages using this scope is currently enabled for debug-level output.

func Debugf 

func Debugf(format string, args ...any)

Debugf uses fmt.Sprintf to construct and log a message at debug level.

func EnableKlogWithCobra 

func EnableKlogWithCobra()

EnableKlogWithCobra enables klog to work with cobra / pflags. k8s libraries like client-go use klog.

func EnableKlogWithGoFlag 

func EnableKlogWithGoFlag()

EnableKlogWithCobra enables klog to work with go flags. k8s libraries like client-go use klog.

func EnableKlogWithVerbosity 

func EnableKlogWithVerbosity(v int)

EnableKlogWithVerbosity sets the klog verbosity directly. When using in an application, EnableKlogWithCobra is preferred to expose a --vklog flag.

func Error 

func Error(fields any)

Error outputs a message at error level.

func ErrorEnabled 

func ErrorEnabled() bool

ErrorEnabled returns whether output of messages using this scope is currently enabled for error-level output.

func Errorf 

func Errorf(format string, args ...any)

Errorf uses fmt.Sprintf to construct and log a message at error level.

func Fatal 

func Fatal(fields any)

Fatal outputs a message at fatal level.

func FatalEnabled 

func FatalEnabled() bool

FatalEnabled returns whether output of messages using this scope is currently enabled for fatal-level output.

func Fatalf 

func Fatalf(format string, args ...any)

Fatalf uses fmt.Sprintf to construct and log a message at fatal level.

func Info 

func Info(fields any)

Info outputs a message at info level.

func InfoEnabled 

func InfoEnabled() bool

InfoEnabled returns whether output of messages using this scope is currently enabled for info-level output.

func Infof 

func Infof(format string, args ...any)

Infof uses fmt.Sprintf to construct and log a message at info level.

func LevelToString 

func LevelToString(level Level) string

func NewLogrAdapter 

func NewLogrAdapter(l *Scope) logr.Logger

NewLogrAdapter creates a new logr.Logger using the given Zap Logger to log.

func Scopes 

func Scopes() map[string]*Scope

Scopes returns a snapshot of the currently defined set of scopes

func Sync 

func Sync() error

Sync flushes any buffered log entries. Processes should normally take care to call Sync before exiting.

func Warn 

func Warn(fields any)

Warn outputs a message at warn level.

func WarnEnabled 

func WarnEnabled() bool

WarnEnabled returns whether output of messages using this scope is currently enabled for warn-level output.

func Warnf 

func Warnf(format string, args ...any)

Warnf uses fmt.Sprintf to construct and log a message at warn level.

Types

type Extension 

type Extension func(c zapcore.Core) (zapcore.Core, func() error, error)

Extension provides an extension mechanism for logs. This is essentially like https://pkg.go.dev/golang.org/x/exp/slog#Handler. This interface should be considered unstable; we will likely swap it for slog in the future and not expose zap internals. Returns a modified Core interface, and a Close() function.

type Level 

type Level int

Level is an enumeration of all supported log levels. 

const (
	// NoneLevel disables logging
	NoneLevel Level = iota
	// FatalLevel enables fatal level logging
	FatalLevel
	// ErrorLevel enables error level logging
	ErrorLevel
	// WarnLevel enables warn level logging
	WarnLevel
	// InfoLevel enables info level logging
	InfoLevel
	// DebugLevel enables debug level logging
	DebugLevel
)

func StringToLevel 

func StringToLevel(level string) Level

type Options 

type Options struct {
	// OutputPaths is a list of file system paths to write the log data to.
	// The special values stdout and stderr can be used to output to the
	// standard I/O streams. This defaults to stdout.
	OutputPaths []string

	// ErrorOutputPaths is a list of file system paths to write logger errors to.
	// The special values stdout and stderr can be used to output to the
	// standard I/O streams. This defaults to stderr.
	ErrorOutputPaths []string

	// JSONEncoding controls whether the log is formatted as JSON.
	JSONEncoding bool
	// contains filtered or unexported fields
}

Options defines the set of options supported by Istio's component logging package.

func DefaultOptions 

func DefaultOptions() *Options

DefaultOptions returns a new set of options, initialized to the defaults

func (*Options) AttachCobraFlags 

func (o *Options) AttachCobraFlags(cmd *cobra.Command)

AttachCobraFlags attaches a set of Cobra flags to the given Cobra command.

Cobra is the command-line processor that Istio uses. This command attaches the necessary set of flags to expose a CLI to let the user control all logging options.

func (*Options) AttachFlags 

func (o *Options) AttachFlags(
	stringArrayVar func(p *[]string, name string, value []string, usage string),
	stringVar func(p *string, name string, value string, usage string),
	_ func(p *int, name string, value int, usage string),
	boolVar func(p *bool, name string, value bool, usage string),
)

AttachFlags allows attaching of flags through a set of lambda functions.

func (*Options) SetDefaultOutputLevel 

func (o *Options) SetDefaultOutputLevel(scope string, level Level)

SetDefaultOutputLevel sets the minimum log output level for a given scope. This can be overwritten by flags

func (*Options) WithExtension 

func (o *Options) WithExtension(e Extension) *Options

func (*Options) WithStackdriverLoggingFormat 

func (o *Options) WithStackdriverLoggingFormat() *Options

WithStackdriverLoggingFormat configures logging output to match Stackdriver structured logging conventions.

func (*Options) WithTeeToUDS 

func (o *Options) WithTeeToUDS(addr, path string) *Options

WithTeeToUDS configures a parallel logging pipeline that writes logs to a server over UDS. addr is the socket that the server listens on, and path is the HTTP path that process the log message.

type Scope 

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

Scope constrains logging control to a named scope level. It gives users a fine grained control over output severity threshold and stack traces.

Scope supports structured logging using WithLabels: 

s := RegisterScope("MyScope", "Description", 0)
s = s.WithLabels("foo", "bar", "baz", 123, "qux", 0.123)
s.Info("Hello")                      // <time>   info   MyScope   Hello  foo=bar baz=123 qux=0.123

The output format can be globally configured to be JSON instead, using Options in this package. 

e.g. <time>   info   MyScope   { "message":"Hello","foo":"bar","baz":123 }

Scope also supports an error dictionary. The caller can pass a *structured.Error object as the first parameter to any of the output functions (Fatal*, Error* etc.) and this will append the fields in the object to the output: 

e := &structured.Error{MoreInfo:"See the documentation in istio.io/helpful_link"}
s.WithLabels("foo", "bar").Error(e, "Hello")
  <time>   info   MyScope   Hello  moreInfo=See the documentation in istio.io/helpful_link foo=bar

See structured.Error for additional guidance on defining errors in a dictionary.

func FindScope 

func FindScope(scope string) *Scope

FindScope returns a previously registered scope, or nil if the named scope wasn't previously registered

func RegisterScope 

func RegisterScope(name string, description string) *Scope

RegisterScope registers a new logging scope. If the same name is used multiple times for a single process, the same Scope struct is returned.

Scope names cannot include colons, commas, or periods.

func WithLabels 

func WithLabels(kvlist ...any) *Scope

WithLabels adds a key-value pairs to the labels in s. The key must be a string, while the value may be any type. It returns a copy of the default scope, with the labels added.

func (*Scope) Debug 

func (s *Scope) Debug(msg any)

Debug outputs a message at debug level.

func (*Scope) DebugEnabled 

func (s *Scope) DebugEnabled() bool

DebugEnabled returns whether output of messages using this scope is currently enabled for debug-level output.

func (*Scope) Debugf 

func (s *Scope) Debugf(format string, args ...any)

Debugf uses fmt.Sprintf to construct and log a message at debug level.

func (*Scope) Description 

func (s *Scope) Description() string

Description returns this scope's description

func (*Scope) Error 

func (s *Scope) Error(msg any)

Error outputs a message at error level.

func (*Scope) ErrorEnabled 

func (s *Scope) ErrorEnabled() bool

ErrorEnabled returns whether output of messages using this scope is currently enabled for error-level output.

func (*Scope) Errorf 

func (s *Scope) Errorf(format string, args ...any)

Errorf uses fmt.Sprintf to construct and log a message at error level.

func (*Scope) Fatal 

func (s *Scope) Fatal(msg any)

Fatal uses fmt.Sprint to construct and log a message at fatal level.

func (*Scope) FatalEnabled 

func (s *Scope) FatalEnabled() bool

FatalEnabled returns whether output of messages using this scope is currently enabled for fatal-level output.

func (*Scope) Fatalf 

func (s *Scope) Fatalf(format string, args ...any)

Fatalf uses fmt.Sprintf to construct and log a message at fatal level.

func (*Scope) GetLogCallers 

func (s *Scope) GetLogCallers() bool

GetLogCallers returns the output level associated with the scope.

func (*Scope) GetOutputLevel 

func (s *Scope) GetOutputLevel() Level

GetOutputLevel returns the output level associated with the scope.

func (*Scope) GetStackTraceLevel 

func (s *Scope) GetStackTraceLevel() Level

GetStackTraceLevel returns the stack tracing level associated with the scope.

func (*Scope) Info 

func (s *Scope) Info(msg any)

Info outputs a message at info level.

func (*Scope) InfoEnabled 

func (s *Scope) InfoEnabled() bool

InfoEnabled returns whether output of messages using this scope is currently enabled for info-level output.

func (*Scope) Infof 

func (s *Scope) Infof(format string, args ...any)

Infof uses fmt.Sprintf to construct and log a message at info level.

func (*Scope) LogWithTime 

func (s *Scope) LogWithTime(level Level, msg string, t time.Time)

LogWithTime outputs a message with a given timestamp.

func (*Scope) Name 

func (s *Scope) Name() string

Name returns this scope's name.

func (*Scope) SetLogCallers 

func (s *Scope) SetLogCallers(logCallers bool)

SetLogCallers adjusts the output level associated with the scope.

func (*Scope) SetOutputLevel 

func (s *Scope) SetOutputLevel(l Level)

SetOutputLevel adjusts the output level associated with the scope.

func (*Scope) SetStackTraceLevel 

func (s *Scope) SetStackTraceLevel(l Level)

SetStackTraceLevel adjusts the stack tracing level associated with the scope.

func (*Scope) Warn 

func (s *Scope) Warn(msg any)

Warn outputs a message at warn level.

func (*Scope) WarnEnabled 

func (s *Scope) WarnEnabled() bool

WarnEnabled returns whether output of messages using this scope is currently enabled for warn-level output.

func (*Scope) Warnf 

func (s *Scope) Warnf(format string, args ...any)

Warnf uses fmt.Sprintf to construct and log a message at warn level.

func (*Scope) WithLabels 

func (s *Scope) WithLabels(kvlist ...any) *Scope

WithLabels adds a key-value pairs to the labels in s. The key must be a string, while the value may be any type. It returns a copy of s, with the labels added. e.g. newScope := oldScope.WithLabels("foo", "bar", "baz", 123, "qux", 0.123)

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.