README

glog
====

Leveled execution logs for Go.

This is an efficient pure Go implementation of leveled logs in the
manner of the open source C++ package
	https://github.com/google/glog

By binding methods to booleans it is possible to use the log package
without paying the expense of evaluating the arguments to the log.
Through the -vmodule flag, the package also provides fine-grained
control over logging at the file level.

The comment from glog.go introduces the ideas:

	Package glog implements logging analogous to the Google-internal
	C++ INFO/ERROR/V setup.  It provides functions Info, Warning,
	Error, Fatal, plus formatting variants such as Infof. It
	also provides V-style logging controlled by the -v and
	-vmodule=file=2 flags.
	
	Basic examples:
	
		glog.Info("Prepare to repel boarders")
	
		glog.Fatalf("Initialization failed: %s", err)
	
	See the documentation for the V function for an explanation
	of these examples:
	
		if glog.V(2) {
			glog.Info("Starting transaction...")
		}
	
		glog.V(2).Infoln("Processed", nItems, "elements")


The repository contains an open source version of the log package
used inside Google. The master copy of the source lives inside
Google, not here. The code in this repo is for export only and is not itself
under development. Feature requests will be ignored.

Send bug reports to golang-nuts@googlegroups.com.
Expand ▾ Collapse ▴

Documentation

Overview

    Package glog implements logging analogous to the Google-internal C++ INFO/ERROR/V setup. It provides functions Info, Warning, Error, Fatal, plus formatting variants such as Infof. It also provides V-style logging controlled by the -v and -vmodule=file=2 flags.

    Basic examples:

    glog.Info("Prepare to repel boarders")
    
    glog.Fatalf("Initialization failed: %s", err)
    

    See the documentation for the V function for an explanation of these examples:

    if glog.V(2) {
    	glog.Info("Starting transaction...")
    }
    
    glog.V(2).Infoln("Processed", nItems, "elements")
    

    Log output is buffered and written periodically using Flush. Programs should call Flush before exiting to guarantee all log output is written.

    By default, all log statements write to files in a temporary directory. This package provides several flags that modify this behavior. As a result, flag.Parse must be called before any logging is done.

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

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var MaxSize uint64 = 1024 * 1024 * 1800

      MaxSize is the maximum size of a log file in bytes.

      View Source
      var Stats struct {
      	Info, Warning, Error OutputStats
      }

        Stats tracks the number of lines of output and number of bytes per severity level. Values must be read with atomic.LoadInt64.

        Functions

        func CopyStandardLogTo

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

          func Error(args ...interface{})

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

            func ErrorDepth

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

              ErrorDepth acts as Error but uses depth to determine which call frame to log. ErrorDepth(0, "msg") is the same as Error("msg").

              func Errorf

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

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

                func Errorln

                func Errorln(args ...interface{})

                  Errorln logs to the ERROR, WARNING, and INFO logs. Arguments are handled in the manner of fmt.Println; a newline is appended if missing.

                  func Exit

                  func Exit(args ...interface{})

                    Exit logs to the FATAL, ERROR, WARNING, and INFO logs, then calls os.Exit(1). Arguments are handled in the manner of fmt.Print; a newline is appended if missing.

                    func ExitDepth

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

                      ExitDepth acts as Exit but uses depth to determine which call frame to log. ExitDepth(0, "msg") is the same as Exit("msg").

                      func Exitf

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

                        Exitf logs to the FATAL, ERROR, WARNING, and INFO logs, then calls os.Exit(1). Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

                        func Exitln

                        func Exitln(args ...interface{})

                          Exitln logs to the FATAL, ERROR, WARNING, and INFO logs, then calls os.Exit(1).

                          func Fatal

                          func Fatal(args ...interface{})

                            Fatal logs to the FATAL, ERROR, WARNING, 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. FatalDepth(0, "msg") is the same as Fatal("msg").

                              func Fatalf

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

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

                                func Fatalln(args ...interface{})

                                  Fatalln logs to the FATAL, ERROR, WARNING, and INFO logs, including a stack trace of all running goroutines, then calls os.Exit(255). Arguments are handled in the manner of fmt.Println; a newline is appended if missing.

                                  func Flush

                                  func Flush()

                                    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.

                                      func InfoDepth

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

                                        InfoDepth acts as Info but uses depth to determine which call frame to log. InfoDepth(0, "msg") is the same as Info("msg").

                                        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 Infoln

                                          func Infoln(args ...interface{})

                                            Infoln logs to the INFO log. Arguments are handled in the manner of fmt.Println; a newline is appended if missing.

                                            func Warning

                                            func Warning(args ...interface{})

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

                                              func WarningDepth

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

                                                WarningDepth acts as Warning but uses depth to determine which call frame to log. WarningDepth(0, "msg") is the same as Warning("msg").

                                                func Warningf

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

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

                                                  func Warningln

                                                  func Warningln(args ...interface{})

                                                    Warningln logs to the WARNING and INFO logs. Arguments are handled in the manner of fmt.Println; a newline is appended if missing.

                                                    Types

                                                    type Level

                                                    type Level int32

                                                      Level specifies a level of verbosity for V logs. *Level implements flag.Value; the -v flag is of type Level and should be modified only through the flag.Value interface.

                                                      func (*Level) Get

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

                                                        Get is part of the flag.Value interface.

                                                        func (*Level) Set

                                                        func (l *Level) Set(value 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 OutputStats

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

                                                              OutputStats tracks the number of output lines and bytes written.

                                                              func (*OutputStats) Bytes

                                                              func (s *OutputStats) Bytes() int64

                                                                Bytes returns the number of bytes written.

                                                                func (*OutputStats) Lines

                                                                func (s *OutputStats) Lines() int64

                                                                  Lines returns the number of lines written.

                                                                  type Verbose

                                                                  type Verbose bool

                                                                    Verbose is a boolean type that implements Infof (like Printf) etc. See the documentation of V for more information.

                                                                    func V

                                                                    func V(level Level) Verbose

                                                                      V reports whether verbosity at the call site is at least the requested level. The returned value is a boolean of type Verbose, which implements Info, Infoln and Infof. These methods will write to the Info log if called. Thus, one may write either

                                                                      if glog.V(2) { glog.Info("log this") }
                                                                      

                                                                      or

                                                                      glog.V(2).Info("log this")
                                                                      

                                                                      The second form is shorter but the first is cheaper if logging is off because it does not evaluate its arguments.

                                                                      Whether an individual call to V generates a log record depends on the setting of the -v and --vmodule flags; both are off by default. If the level in the call to V is at least the value of -v, or of -vmodule for the source file containing the call, the V call will log.

                                                                      func (Verbose) Info

                                                                      func (v Verbose) Info(args ...interface{})

                                                                        Info is equivalent to the global Info function, guarded by the value of v. See the documentation of V for usage.

                                                                        func (Verbose) Infof

                                                                        func (v Verbose) Infof(format string, args ...interface{})

                                                                          Infof is equivalent to the global Infof function, guarded by the value of v. See the documentation of V for usage.

                                                                          func (Verbose) Infoln

                                                                          func (v Verbose) Infoln(args ...interface{})

                                                                            Infoln is equivalent to the global Infoln function, guarded by the value of v. See the documentation of V for usage.