vlog

package
Version: v0.1.10 Latest Latest
Warning

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

Go to latest
Published: Dec 13, 2021 License: BSD-3-Clause Imports: 7 Imported by: 87

Documentation

Overview

Package vlog implements a general-purpose logging system. It is modeled on glog; the differences from glog are:

- interfaces are used to allow for multiple implementations and instances. In particular, application and runtime logging can be separated. We also expect to stream log messages to external log collectors rather to local storage.

- the Warn family of methods are not provided; their main use is to avoid the flush that's implicit in the Error routines rather than any semantic difference between warnings and errors.

- Info logging and Event logging is separated with the former expected to be somewhat spammy and the latter to be used sparingly.

- Event logging includes methods for unconditionally (i.e. regardless of any command line options) logging the current goroutine's stack or the stacks of all goroutines.

- The use of interfaces and encapsulated state means that a single function (V) can no longer be used for 'if guarded' and 'chained' logging. That is:

if vlog.V(1) { ... } and vlog.V(1).Infof( ... )

becomes

if logger.V(1) { ... }  and logger.VI(1).Infof( ... )

vlog also creates a global instance of the Logger (vlog.Log) and provides command line flags (see flags.go). Parsing of these flags is performed by calling one of ConfigureLibraryLoggerFromFlags or ConfigureLoggerFromFlags .

The supported flags are:

-logtostderr=false
	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".
-max_stack_buf_size=<size in bytes>
	Set the max size (bytes) of the byte buffer to use for stack
	traces. The default max is 4M; use powers of 2 since the
	stack size will be grown exponentially until it exceeds the max.
	A min of 128K is enforced and any attempts to reduce this will
	be silently ignored.

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	// InfoLog etc reexport the logging severity levels from the underlying llog package.
	InfoLog    = llog.InfoLog
	WarningLog = llog.WarningLog
	ErrorLog   = llog.ErrorLog
	FatalLog   = llog.FatalLog

	CommandLineLoggingFlags LoggingFlags
)

Functions

func Configure

func Configure(opts ...LoggingOpts) error

ConfigureLogging configures all future logging. Some options may not be usable if ConfigureLogging is called from an init function, in which case an error will be returned. The Configured error is returned if ConfigureLogger has already been called unless the OverridePriorConfiguration options is included.

Example
package main

import (
	"v.io/x/lib/vlog"
)

func main() {
	vlog.Configure()
}
Output:

func ConfigureLibraryLoggerFromFlags

func ConfigureLibraryLoggerFromFlags() error

ConfigureLibraryLoggerFromFlags will configure the internal global logger using command line flags. It assumes that flag.Parse() has already been called to initialize the flag variables.

func Error

func Error(args ...interface{})

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

Example
package main

import (
	"v.io/x/lib/vlog"
)

func main() {
	vlog.Errorf("%s", "error")
	if vlog.V(2) {
		vlog.Info("some spammy message")
	}
	vlog.VI(2).Infof("another spammy message")
}
Output:

func ErrorDepth

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

ErrorDepth acts as Error but uses depth to determine which call frame to log. A depth of 0 is equivalent to calling Error.

func Errorf

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

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

func Fatal

func Fatal(args ...interface{})

Fatal logs to the FATAL, ERROR 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. A depth of 0 is equivalent to calling Fatal.

func Fatalf

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

Fatalf logs to the FATAL, ERROR 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 FlushLog

func FlushLog()

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.

Example
package main

import (
	"v.io/x/lib/vlog"
)

func main() {
	vlog.Info("hello")
}
Output:

func InfoDepth

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

InfoDepth acts as Info but uses depth to determine which call frame to log. A depth of 0 is equivalent to calling Info.

func InfoFileLine added in v0.1.4

func InfoFileLine(file string, line int, args ...interface{})

InfoFileLine acts as Info but uses file and line as the call frame to log.

func InfoStack

func InfoStack(all bool)

InfoStack logs the current goroutine's stack if the all parameter is false, or the stacks of all goroutines if it's true.

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 Panic

func Panic(args ...interface{})

Panic is equivalent to Error() followed by a call to panic().

func PanicDepth

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

PanicDepth acts as Panic but uses depth to determine which call frame to log. A depth of 0 is equivalent to calling Panic.

func Panicf

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

Panicf is equivalent to Errorf() followed by a call to panic().

func RegisterLoggingFlags

func RegisterLoggingFlags(fs *flag.FlagSet, lf *LoggingFlags, prefix string)

RegisterLoggingFlags registers the logging flags with the specified flagset and with prefix prepepended to their flag names.

--<prefix>v  NOTE, see below
--<prefix>log_dir
--<prefix>logtostderr
--<prefix>alsologtostderr
--<prefix>max_stack_buf_size
--<prefix>stderrthreshold
--<prefix>vmodule
--<prefix>vpath
--<prefix>log_backtrace_at

The verbosity flag is problematic with go test since it also uses --v or --test.v when the test is compiled. If --test.v is already defined RegisterLoggingFlags will use --<prefix>vlevel instead of -v.

func Stats

func Stats() (infoStats, errorStats struct{ Lines, Bytes int64 })

Stats returns stats on how many lines/bytes haven been written to this set of logs.

func V

func V(level Level) bool

V returns true if the configured logging level is greater than or equal to its parameter

func VDepth added in v0.1.4

func VDepth(depth int, level Level) bool

VDepth acts as V but uses depth to determine which call frame to check V. A depth of 0 is equivalent to calling V.

func VI

func VI(level Level) interface {
	// Info logs to the INFO log.
	// Arguments are handled in the manner of fmt.Print; a newline is appended if missing.
	Info(args ...interface{})

	// Infoln logs to the INFO log.
	// Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.
	Infof(format string, args ...interface{})

	// InfoDepth acts as Info but uses depth to determine which call frame to log.
	// A depth of 0 is equivalent to calling Info.
	InfoDepth(depth int, args ...interface{})

	// InfoStack logs the current goroutine's stack if the all parameter
	// is false, or the stacks of all goroutines if it's true.
	InfoStack(all bool)
}

VI is like V, except that it returns an instance of the Info interface that will either log (if level >= the configured level) or discard its parameters. This allows for logger.VI(2).Info style usage.

Types

type AlsoLogToStderr

type AlsoLogToStderr bool

func (AlsoLogToStderr) LoggingOpt

func (AlsoLogToStderr) LoggingOpt()

If true, logs are written to standard error as well as to files.

type AutoFlush

type AutoFlush bool

func (AutoFlush) LoggingOpt

func (AutoFlush) LoggingOpt()

If true, enables automatic flushing of log output on every call

type FilepathSpec

type FilepathSpec struct {
	llog.FilepathSpec
}

FilepathSpec allows for the setting of specific log levels for specific files matched by a regular expression. The syntax is <re>=3,<re1>=2. It can be set via the FilepathSpec optional parameter to Configure. It implements the flag.Value interface to support command line option parsing.

func (FilepathSpec) LoggingOpt

func (FilepathSpec) LoggingOpt()

The syntax of the argument is a comma-separated list of regexp=N, where pattern is a regular expression matched against the full path name of files and N is a V level. For instance, myco.com/web/.*=3 sets the V level to 3 in all Go files whose path names match myco.com/web/.*".

type Level

type Level llog.Level

Level specifies a level of verbosity for V logs. It can be set via the Level optional parameter to Configure. It implements the flag.Value interface to support command line option parsing.

func (*Level) Get

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

Get is part of the flag.Value interface.

func (Level) LoggingOpt

func (Level) LoggingOpt()

Enable V-leveled logging at the specified level.

func (*Level) Set

func (l *Level) Set(v 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 LogDir

type LogDir string

func (LogDir) LoggingOpt

func (LogDir) LoggingOpt()

log files will be written to this directory instead of the default temporary directory.

type LogToStderr

type LogToStderr bool

func (LogToStderr) LoggingOpt

func (LogToStderr) LoggingOpt()

If true, logs are written to standard error instead of to files.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}
var (
	Log           *Logger
	ErrConfigured = errors.New("logger has already been configured")
)

func NewLogger

func NewLogger(name string) *Logger

NewLogger creates a new instance of the logging interface.

func (*Logger) Configure

func (l *Logger) Configure(opts ...LoggingOpts) error

Configure configures all future logging. Some options may not be usable if ConfigureLogging is called from an init function, in which case an error will be returned. The Configured error is returned if ConfigureLogger has already been called unless the OverridePriorConfiguration options is included. nolint: gocyclo

func (*Logger) ConfigureFromArgs

func (l *Logger) ConfigureFromArgs(opts ...LoggingOpts) error

ConfigureFromArgs will configure the logger using the supplied args.

func (*Logger) ConfigureFromFlags

func (l *Logger) ConfigureFromFlags(opts ...LoggingOpts) error

ConfigureFromFlags will configure the logger using command line flags.

func (*Logger) ConfigureFromLoggingFlags

func (l *Logger) ConfigureFromLoggingFlags(lf *LoggingFlags, opts ...LoggingOpts) error

ConfigureFromLoggingFlags will configure the logger using the specified LoggingFlags.

func (*Logger) CopyStandardLogTo added in v0.1.4

func (l *Logger) 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 (*Logger) Error

func (l *Logger) Error(args ...interface{})

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

func (*Logger) ErrorDepth

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

ErrorDepth acts as Error but uses depth to determine which call frame to log. A depth of 0 is equivalent to calling Error.

func (*Logger) Errorf

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

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

func (*Logger) ExplicitlySetFlags

func (l *Logger) ExplicitlySetFlags() map[string]string

ExplicitlySetFlags returns a map of the logging command line flags and their values formatted as strings. Only the flags that were explicitly set are returned. This is intended for use when an application needs to know what value the flags were set to, for example when creating subprocesses.

func (*Logger) Fatal

func (l *Logger) Fatal(args ...interface{})

Fatal logs to the FATAL, ERROR 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 (*Logger) FatalDepth

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

FatalDepth acts as Fatal but uses depth to determine which call frame to log. A depth of 0 is equivalent to calling Fatal.

func (*Logger) Fatalf

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

Fatalf logs to the FATAL, ERROR 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 (*Logger) FlushLog

func (l *Logger) FlushLog()

Flush flushes all pending log I/O.

func (*Logger) Info

func (l *Logger) 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 (*Logger) InfoDepth

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

InfoDepth acts as Info but uses depth to determine which call frame to log. A depth of 0 is equivalent to calling Info.

func (*Logger) InfoStack

func (l *Logger) InfoStack(all bool)

InfoStack logs the current goroutine's stack if the all parameter is false, or the stacks of all goroutines if it's true.

func (*Logger) Infof

func (l *Logger) 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 (*Logger) LogDir

func (l *Logger) LogDir() string

LogDir returns the directory where the log files are written.

func (*Logger) Panic

func (l *Logger) Panic(args ...interface{})

Panic is equivalent to Error() followed by a call to panic().

func (*Logger) PanicDepth

func (l *Logger) PanicDepth(depth int, args ...interface{})

PanicDepth acts as Panic but uses depth to determine which call frame to log. A depth of 0 is equivalent to calling Panic.

func (*Logger) Panicf

func (l *Logger) Panicf(format string, args ...interface{})

Panicf is equivalent to Errorf() followed by a call to panic().

func (*Logger) Stats

func (l *Logger) Stats() (infoStats, errorStarts struct{ Lines, Bytes int64 })

Stats returns stats on how many lines/bytes haven been written to this set of logs.

func (*Logger) String

func (l *Logger) String() string

String implements string.Stringer.

func (*Logger) V

func (l *Logger) V(v int) bool

func (*Logger) VDepth

func (l *Logger) VDepth(depth int, v int) bool

func (*Logger) VI

func (l *Logger) VI(v int) interface {
	// Info logs to the INFO log.
	// Arguments are handled in the manner of fmt.Print; a newline is appended if missing.
	Info(args ...interface{})

	// Infoln logs to the INFO log.
	// Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.
	Infof(format string, args ...interface{})

	// InfoDepth acts as Info but uses depth to determine which call frame to log.
	// A depth of 0 is equivalent to calling Info.
	InfoDepth(depth int, args ...interface{})

	// InfoStack logs the current goroutine's stack if the all parameter
	// is false, or the stacks of all goroutines if it's true.
	InfoStack(all bool)
}

func (*Logger) VIDepth

func (l *Logger) VIDepth(depth int, v int) interface {
	// Info logs to the INFO log.
	// Arguments are handled in the manner of fmt.Print; a newline is appended if missing.
	Info(args ...interface{})

	// Infoln logs to the INFO log.
	// Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.
	Infof(format string, args ...interface{})

	// InfoDepth acts as Info but uses depth to determine which call frame to log.
	// A depth of 0 is equivalent to calling Info.
	InfoDepth(depth int, args ...interface{})

	// InfoStack logs the current goroutine's stack if the all parameter
	// is false, or the stacks of all goroutines if it's true.
	InfoStack(all bool)
}

type LoggingFlags

type LoggingFlags struct {
	ToStderr        bool
	AlsoToStderr    bool
	LogDir          string
	Verbosity       Level
	StderrThreshold StderrThreshold
	VModule         ModuleSpec
	VPath           FilepathSpec
	TraceLocation   TraceLocation
	MaxStackBufSize int
}

LoggingFlags represents all of the flags that can be used to configure logging.

type LoggingOpts

type LoggingOpts interface {
	LoggingOpt()
}

type MaxStackBufSize

type MaxStackBufSize int

func (MaxStackBufSize) LoggingOpt

func (MaxStackBufSize) LoggingOpt()

Set the max size (bytes) of the byte buffer to use for stack traces. The default max is 4M; use powers of 2 since the stack size will be grown exponentially until it exceeds the max. A min of 128K is enforced and any attempts to reduce this will be silently ignored.

type ModuleSpec

type ModuleSpec struct {
	llog.ModuleSpec
}

ModuleSpec allows for the setting of specific log levels for specific modules. The syntax is recordio=2,file=1,gfs*=3 It can be set via the ModuleSpec optional parameter to Configure. It implements the flag.Value interface to support command line option parsing.

func (ModuleSpec) LoggingOpt

func (ModuleSpec) LoggingOpt()

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, gopher*=3 sets the V level to 3 in all Go files whose names begin "gopher".

type OverridePriorConfiguration

type OverridePriorConfiguration bool

func (OverridePriorConfiguration) LoggingOpt

func (OverridePriorConfiguration) LoggingOpt()

If true, allows this call to ConfigureLogger to override a prior configuration.

type StderrThreshold

type StderrThreshold llog.Severity

StderrThreshold identifies the sort of log: info, warning etc. The values match the corresponding constants in C++ - e.g WARNING etc. It can be set via the StderrThreshold optional parameter to Configure. It implements the flag.Value interface to support command line option parsing.

func (*StderrThreshold) Get

func (s *StderrThreshold) Get(v string) interface{}

Get is part of the flag.Value interface.

func (StderrThreshold) LoggingOpt

func (StderrThreshold) LoggingOpt()

Log events at or above this severity are logged to standard error as well as to files.

func (*StderrThreshold) Set

func (s *StderrThreshold) Set(v string) error

Set is part of the flag.Value interface.

func (*StderrThreshold) String

func (s *StderrThreshold) String() string

String is part of the flag.Value interface.

type TraceLocation

type TraceLocation struct {
	llog.TraceLocation
}

TraceLocation specifies the location, file:N, which when encountered will cause logging to emit a stack trace. It can be set via the TraceLocation optional parameter to Configure. It implements the flag.Value interface to support command line option parsing.

func (TraceLocation) LoggingOpt

func (TraceLocation) LoggingOpt()

When set to a file and line number holding a logging statement, such as

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.)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL