log

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

• func Configure(options *Options) error
• func Debug(msg string, fields ...zapcore.Field)
• func DebugEnabled() bool
• func Debuga(args ...interface{})
• func Debugf(template string, args ...interface{})
• func Debugw(msg string, keysAndValues ...interface{})
• func Error(msg string, fields ...zapcore.Field)
• func ErrorEnabled() bool
• func Errora(args ...interface{})
• func Errorf(template string, args ...interface{})
• func Errorw(msg string, keysAndValues ...interface{})
• func Info(msg string, fields ...zapcore.Field)
• func InfoEnabled() bool
• func Infoa(args ...interface{})
• func Infof(template string, args ...interface{})
• func Infow(msg string, keysAndValues ...interface{})
• func Sync() error
• func Warn(msg string, fields ...zapcore.Field)
• func WarnEnabled() bool
• func Warna(args ...interface{})
• func Warnf(template string, args ...interface{})
• func Warnw(msg string, keysAndValues ...interface{})
• func With(fields ...zapcore.Field) *zap.Logger
• type Level
• type Options
  • func DefaultOptions() *Options
  • func (o *Options) AttachCobraFlags(cmd *cobra.Command)
  • func (o *Options) GetOutputLevel() (Level, error)
  • func (o *Options) GetStackTraceLevel() (Level, error)
  • func (o *Options) SetOutputLevel(level Level) error
  • func (o *Options) SetStackTraceLevel(level Level) error

Functions

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.

func Debug

func Debug(msg string, fields ...zapcore.Field)

Debug outputs a message at debug level. This call is a wrapper around [Logger.Debug](https://godoc.org/go.uber.org/zap#Logger.Debug)

func DebugEnabled

func DebugEnabled() bool

DebugEnabled returns whether output of messages at the debug level is currently enabled.

func Debuga

func Debuga(args ...interface{})

Debuga uses fmt.Sprint to construct and log a message at debug level. This call is a wrapper around [Sugaredlogger.Debug](https://godoc.org/go.uber.org/zap#Sugaredlogger.Debug)

func Debugf

func Debugf(template string, args ...interface{})

Debugf uses fmt.Sprintf to construct and log a message at debug level. This call is a wrapper around [Sugaredlogger.Debugf](https://godoc.org/go.uber.org/zap#Sugaredlogger.Debugf)

func Debugw

func Debugw(msg string, keysAndValues ...interface{})

Debugw logs a message at debug level with some additional context. This call is a wrapper around [Sugaredlogger.Debugw](https://godoc.org/go.uber.org/zap#Sugaredlogger.Debugw)

func Error

func Error(msg string, fields ...zapcore.Field)

Error outputs a message at error level. This call is a wrapper around [logger.Error](https://godoc.org/go.uber.org/zap#logger.Error)

func ErrorEnabled

func ErrorEnabled() bool

ErrorEnabled returns whether output of messages at the error level is currently enabled.

func Errora

func Errora(args ...interface{})

Errora uses fmt.Sprint to construct and log a message at error level. This call is a wrapper around [Sugaredlogger.Error](https://godoc.org/go.uber.org/zap#Sugaredlogger.Error)

func Errorf

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

Errorf uses fmt.Sprintf to construct and log a message at error level. This call is a wrapper around [Sugaredlogger.Errorf](https://godoc.org/go.uber.org/zap#Sugaredlogger.Errorf)

func Errorw

func Errorw(msg string, keysAndValues ...interface{})

Errorw logs a message at error level with some additional context. This call is a wrapper around [Sugaredlogger.Errorw](https://godoc.org/go.uber.org/zap#Sugaredlogger.Errorw)

func Info

func Info(msg string, fields ...zapcore.Field)

Info outputs a message at information level. This call is a wrapper around [logger.Info](https://godoc.org/go.uber.org/zap#logger.Info)

func InfoEnabled

func InfoEnabled() bool

InfoEnabled returns whether output of messages at the info level is currently enabled.

func Infoa

func Infoa(args ...interface{})

Infoa uses fmt.Sprint to construct and log a message at info level. This call is a wrapper around [Sugaredlogger.Info](https://godoc.org/go.uber.org/zap#Sugaredlogger.Info)

func Infof

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

Infof uses fmt.Sprintf to construct and log a message at info level. This call is a wrapper around [Sugaredlogger.Infof](https://godoc.org/go.uber.org/zap#Sugaredlogger.Infof)

func Infow

func Infow(msg string, keysAndValues ...interface{})

Infow logs a message at info level with some additional context. This call is a wrapper around [Sugaredlogger.Infow](https://godoc.org/go.uber.org/zap#Sugaredlogger.Infow)

func Sync

func Sync() error

Sync flushes any buffered log entries. Processes should normally take care to call Sync before exiting. This call is a wrapper around [logger.Sync](https://godoc.org/go.uber.org/zap#logger.Sync)

func Warn

func Warn(msg string, fields ...zapcore.Field)

Warn outputs a message at warn level. This call is a wrapper around [logger.Warn](https://godoc.org/go.uber.org/zap#logger.Warn)

func WarnEnabled

func WarnEnabled() bool

WarnEnabled returns whether output of messages at the warn level is currently enabled.

func Warna

func Warna(args ...interface{})

Warna uses fmt.Sprint to construct and log a message at warn level. This call is a wrapper around [Sugaredlogger.Warn](https://godoc.org/go.uber.org/zap#Sugaredlogger.Warn)

func Warnf

func Warnf(template string, args ...interface{})

Warnf uses fmt.Sprintf to construct and log a message at warn level. This call is a wrapper around [Sugaredlogger.Warnf](https://godoc.org/go.uber.org/zap#Sugaredlogger.Warnf)

func Warnw

func Warnw(msg string, keysAndValues ...interface{})

Warnw logs a message at warn level with some additional context. This call is a wrapper around [Sugaredlogger.Warnw](https://godoc.org/go.uber.org/zap#Sugaredlogger.Warnw)

func With

func With(fields ...zapcore.Field) *zap.Logger

With creates a child logger and adds structured context to it. Fields added to the child don't affect the parent, and vice versa. This call is a wrapper around [logger.With](https://godoc.org/go.uber.org/zap#logger.With)

Types

type Level

type Level string

Level is an enumeration of all supported log levels.

const (
	// DebugLevel enables debug level logging
	DebugLevel Level = "debug"
	// InfoLevel enables info level logging
	InfoLevel Level = "info"
	// WarnLevel enables warn level logging
	WarnLevel Level = "warn"
	// ErrorLevel enables error level logging
	ErrorLevel Level = "error"
	// NoneLevel disables logging
	NoneLevel Level = "none"
)

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

	// RotateOutputPath is the path to a rotating log file. This file should
	// be automatically rotated over time, based on the rotation parameters such
	// as RotationMaxSize and RotationMaxAge. The default is to not rotate.
	//
	// This path is used as a foundational path. This is where log output is normally
	// saved. When a rotation needs to take place because the file got too big or too
	// old, then the file is renamed by appending a timestamp to the name. Such renamed
	// files are called backups. Once a backup has been created,
	// output resumes to this path.
	RotateOutputPath string

	// RotationMaxSize is the maximum size in megabytes of a log file before it gets
	// rotated. It defaults to 100 megabytes.
	RotationMaxSize int

	// RotationMaxAge is the maximum number of days to retain old log files based on the
	// timestamp encoded in their filename. Note that a day is defined as 24
	// hours and may not exactly correspond to calendar days due to daylight
	// savings, leap seconds, etc. The default is to remove log files
	// older than 30 days.
	RotationMaxAge int

	// RotationMaxBackups is the maximum number of old log files to retain.  The default
	// is to retain at most 1000 logs.
	RotationMaxBackups int

	// JSONEncoding controls whether the log is formatted as JSON.
	JSONEncoding bool

	// IncludeCallerSourceLocation determines whether log messages include the source location of the caller.
	IncludeCallerSourceLocation bool

	// LogGrpc indicates that Grpc logs should be captured. The default is true.
	// This is not exposed through the command-line flags, as this flag is mainly useful for testing: Grpc
	// stack will hold on to the logger even though it gets closed. This causes data races.
	LogGrpc 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) GetOutputLevel

func (o *Options) GetOutputLevel() (Level, error)

GetOutputLevel returns the minimum log output level.

func (*Options) GetStackTraceLevel

func (o *Options) GetStackTraceLevel() (Level, error)

GetStackTraceLevel returns the current stack trace level.

func (*Options) SetOutputLevel

func (o *Options) SetOutputLevel(level Level) error

SetOutputLevel sets the minimum log output level.

func (*Options) SetStackTraceLevel

func (o *Options) SetStackTraceLevel(level Level) error

SetStackTraceLevel sets the minimum stack trace capture level.