flog

package module
v0.0.0-...-d2511d0 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2019 License: Apache-2.0 Imports: 14 Imported by: 107

README

flog

Build Status GoDoc

Flog is a hacked and slashed version of glog that can be used as a drop in replacement for the latter.

Overview

Flog was originally created to facilitate logging from within libraries but can be used in main programs as well.

To this end, this library has some significant differences, compared to the original glog. Namely:

  • It only logs to stderr. Logging to files, along with all relevant flags and tests has been removed.
  • It supports configuration through env vars as well as a configuration struct that allows for more flexibility when using the lib.
  • Users can log immediately without first having to call flag.Parse().
  • It only adds flags for the lib explicitly.
  • It has a different buffer allocation mechanism that works faster in scenarios where parallel logging is required (see the BenchmarkHeaderParallel).
  • Support to get the current verbosity level.
  • Support to set a different output writer.
  • Two more severity levels added, DEBUG and CRITICAL, along with their relevant Debug*() and Critical*() functions.

However, the important parts of glog have been retained, such as:

  • The V() functionality remains the same.
  • Users can use Info*(), Warning*(), Error*() and Fatal*() functions as before.
  • Filtering through module name and tracebacks are supported in exactly the same way as in glog.

Configuration

As noted above configuration is possible through different ways. We outline them below.

Environment Variables

flog supports 3 different env vars for configuring its behavior. These are:

  • FLOG_VERBOSITY - takes an int > 0 argument and will set the overall Verbosity for the lib.
  • FLOG_VMODULE - takes a string argument containing a pattern which is then used to filter logs from different module thus allowing to setup different verbosities for different parts of the program.
  • FLOG_LOG_BACKTRACE_AT - takes a string argument so that when logging from a particular line in a particular file a stack trace is also printed.

These vars are considered during package initialization through its init() function.

CLI flags

As with the original glog, flog also supports adding flags that configure the behavior described above. The flags are -v, -vmodule and -log_backtrace_at and their meaning is equivalent to the env vars described above. Unlike glog however, these flags are added only after an explicit call to the AddFlags() function of the package and only support the flag Go package. This call will add all flags to a given flag set. The second argument is a config structure (cf. Section 2.3) which, if not nil, will have its Set() method called before setting any flags. This function returns either any errors produced by Set() or nil.

The Config structure

This is a flexible interface that we've added to allow programs to create more complex logging configurations where parts of the program may log with different verbosities and can request different filters.

The struct contains the following members, Verbosity, Vmodule and TraceLocation and their meaning is the same as the flags described above. All the members of this struct are strings. The caller must call the Set() method of this struct to set the values. This method is concurrency-safe.

Precedence

The order by which this lib honors the above configuration options is:

  1. Environment Variables
  2. Flags
  3. Any values set through Config objects
Defaults

The default values are as follows:

  • Verbosity = 0
  • Vmodule = ""
  • Log Backtrace At = ""

License

Flog is published under the Apache v2.0 License.

Documentation

Overview

Package flog is a hacked and slashed version of glog that only logs in stderr and can be configured with env vars.

Copyright 2019-present Facebook Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package flog is a hacked and slashed version of glog that only logs in stderr and can be configured with env vars.

Copyright 2019-present Facebook Inc. All Rights Reserved. Copyright 2013 Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. 

-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 Stats struct {
	Debug, Info, Warning, Error, Critical 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 AddFlags 

func AddFlags(fs *flag.FlagSet, defaults *Config) error

AddFlags allows the caller to add the flags for configuring this module to the specified FlagSet which can then be used to arbitrary flag libs. For the Go flag lib use flag.CommandLine. If defaults is not nil this function will first call its Set() method.

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 "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", and "FATAL". If the name is not recognized, CopyStandardLogTo panics.

func Critical 

func Critical(args ...interface{})

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

func CriticalDepth 

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

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

func Criticalf 

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

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

func Criticalln 

func Criticalln(args ...interface{})

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

func Debug 

func Debug(args ...interface{})

Debug logs to the DEBUG log. Arguments are handled in the manner of fmt.Print; a newline is appended if missing.

func DebugDepth 

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

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

func Debugf 

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

Debugf logs to the DEBUG log. Arguments are handled in the manner of fmt.Printf; a newline is appended if missing.

func Debugln 

func Debugln(args ...interface{})

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

func Error 

func Error(args ...interface{})

Error logs to the ERROR, WARNING, INFO and DEBUG 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, INFO and DEBUG 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, INFO and DEBUG 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, CRITICAL, ERROR, WARNING, INFO and DEBUG 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, CRITICAL, ERROR, WARNING, INFO and DEBUG 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, CRITICAL, ERROR, WARNING, INFO and DEBUG logs, then calls os.Exit(1).

func Fatal 

func Fatal(args ...interface{})

Fatal logs to the FATAL, CRITICAL, ERROR, WARNING, INFO and DEBUG 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, CRITICAL, ERROR, WARNING, INFO and DEBUG 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, CRITICAL, ERROR, WARNING, INFO and DEBUG 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 Flags 

func Flags() *flag.FlagSet

Flags creates a new Go stdlib flag.FlagSet and returns it. This promotes easier interop with other flag libraries that don't easily expose the underlying flag.FlagSet.

func FlagsWithDefaults 

func FlagsWithDefaults(defaults *Config) (*flag.FlagSet, error)

FlagsWithDefaults mimics Flags above, but allows for passing in default config values.

func Info 

func Info(args ...interface{})

Info logs to the INFO and DEBUG 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 and DEBUG 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 and DEBUG log. Arguments are handled in the manner of fmt.Println; a newline is appended if missing.

func SetOutput 

func SetOutput(w io.Writer)

SetOutput sets the output writer for the lib.

func Warning 

func Warning(args ...interface{})

Warning logs to the WARNING, INFO and DEBUG 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, INFO and DEBUG 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, INFO and DEBUG logs. Arguments are handled in the manner of fmt.Println; a newline is appended if missing.

Types

type Config 

type Config struct {
	Verbosity     string
	Vmodule       string
	TraceLocation string
}

Config struct provides an alternative way to configure this lib. Callers must call the Set() method once defining the values.

func (*Config) Set 

func (c *Config) Set() error

Set sets the configuration for the lib using the values of the struct. This function is safe to use concurrently.

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 GetVerbosity 

func GetVerbosity() Level

GetVerbosity gets the current verbosity level

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.

Source Files

View all Source files

Directories

Path Synopsis

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.