vlog

package
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: 108

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

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.