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

                          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

                                            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

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