golog

README

golog   

Provides logging used in many getlantern components.

GoDoc

Documentation

Overview

Package golog implements logging functions that log errors to stderr and debug messages to stdout.

Trace logs go to stdout as well, but they are only written if a linker flag or an environment variable is set as such:

- The following linker flag is set

	-X github.com/getlantern/golog.linkerFlagEnableTraceThroughLinker=true

  - Optionally, you can also set a comma-separated list of prefixes to trace
    through the following linker flag

    -X github.com/getlantern/golog.linkerFlagTracePrefixes=prefix1,prefix2

  - Or, alternatively, trace logging can also be enable if "TRACE=true"
    environment variable is set

  - Optionally, you can also set a comma-separated list of prefixes to trace
    through the "TRACE" environment variable like this: "TRACE=prefix1,prefix2"

A stack dump will be printed after the message if "PRINT_STACK=true".

Index

• Constants
• func DefaultOnFatal()
• func GetPrepender() func(io.Writer)
• func OnFatal(fn func(err error))
• func RegisterReporter(reporter ErrorReporter)
• func ResetOutputs()
• func ResetPrepender()
• func SetOutput(out Output) (reset func())
• func SetOutputs(errorOut io.Writer, debugOut io.Writer) (reset func())
• func SetPrepender(p func(io.Writer))
• type ErrorReporter
• type Event
• type Logger
  • func LoggerFor(prefix string) Logger
• type MultiLine
• type Output
  • func JsonOutput(errorWriter io.Writer, debugWriter io.Writer) Output
  • func TextOutput(errorWriter io.Writer, debugWriter io.Writer) Output
  • func ZapOutput(zapLogger *zap.Logger) Output
• type Severity
  • func (s Severity) String() string

Constants

const (
	// ERROR is an error Severity
	ERROR = 500

	// FATAL is an error Severity
	FATAL = 600
)

Functions

func DefaultOnFatal

func DefaultOnFatal()

DefaultOnFatal enables the default behavior for OnFatal

func GetPrepender

func GetPrepender() func(io.Writer)

func OnFatal

func OnFatal(fn func(err error))

OnFatal configures golog to call the given function on any FATAL error. By default, golog calls os.Exit(1) on any FATAL error.

func RegisterReporter

func RegisterReporter(reporter ErrorReporter)

RegisterReporter registers the given ErrorReporter. All logged Errors are sent to this reporter.

func ResetOutputs

func ResetOutputs()

Deprecated: instead of calling ResetOutputs, use the reset function returned by SetOutputs.

func ResetPrepender

func ResetPrepender()

func SetOutput

func SetOutput(out Output) (reset func())

SetOutput sets the Output to use for errors and debug messages

func SetOutputs

func SetOutputs(errorOut io.Writer, debugOut io.Writer) (reset func())

SetOutputs sets the outputs for error and debug logs to use the given Outputs. Returns a function that resets outputs to their original values prior to calling SetOutputs. If env variable PRINT_JSON is set, use JSON output instead of plain text

func SetPrepender

func SetPrepender(p func(io.Writer))

SetPrepender sets a function to write something, e.g., the timestamp, before each line of the log.

Types

type ErrorReporter

type ErrorReporter func(err error, severity Severity, ctx map[string]interface{})

ErrorReporter is a function to which the logger will report errors. It the given error and corresponding message along with associated ops context. This should return quickly as it executes on the critical code path. The recommended approach is to buffer as much as possible and discard new reports if the buffer becomes saturated.

type Event

type Event struct {
	Message   string                 `json:"msg,omitempty"`
	Component string                 `json:"component,omitempty"`
	Caller    string                 `json:"caller,omitempty"`
	Context   map[string]interface{} `json:"context,omitempty"`
	Severity  string                 `json:"level,omitempty"`
	Stack     string                 `json:"stack,omitempty"`
}

type Logger

type Logger interface {
	// Debug logs to stdout
	Debug(arg interface{})
	// Debugf logs to stdout
	Debugf(message string, args ...interface{})

	// Error logs to stderr
	Error(arg interface{}) error
	// Errorf logs to stderr. It returns the first argument that's an error, or
	// a new error built using fmt.Errorf if none of the arguments are errors.
	Errorf(message string, args ...interface{}) error

	// Fatal logs to stderr and then exits with status 1
	Fatal(arg interface{})
	// Fatalf logs to stderr and then exits with status 1
	Fatalf(message string, args ...interface{})

	// Trace logs to stderr only if TRACE=true
	Trace(arg interface{})
	// Tracef logs to stderr only if TRACE=true
	Tracef(message string, args ...interface{})

	// TraceOut provides access to an io.Writer to which trace information can
	// be streamed. If running with environment variable "TRACE=true", TraceOut
	// will point to os.Stderr, otherwise it will point to a ioutil.Discared.
	// Each line of trace information will be prefixed with this Logger's
	// prefix.
	TraceOut() io.Writer

	// IsTraceEnabled() indicates whether or not tracing is enabled for this
	// logger.
	IsTraceEnabled() bool

	// AsDebugLogger returns an standard logger that writes Debug messages
	AsDebugLogger() *log.Logger

	// AsStdLogger returns an standard logger that writes Errors
	AsStdLogger() *log.Logger

	// AsErrorLogger returns an standard logger that writes Errors
	AsErrorLogger() *log.Logger
}

func LoggerFor

func LoggerFor(prefix string) Logger

type MultiLine

type MultiLine interface {
	// MultiLinePrinter returns a function that can be used to print the
	// multi-line output. The returned function writes one line to the buffer and
	// returns true if there are more lines to write. This function does not need
	// to take care of trailing carriage returns, golog handles that
	// automatically.
	MultiLinePrinter() func(buf *bytes.Buffer) bool
}

MultiLine is an interface for arguments that support multi-line output.

type Output

type Output interface {
	// Write debug messages
	Debug(prefix string, skipFrames int, printStack bool, severity string, arg interface{}, values map[string]interface{})

	// Write error messages
	Error(prefix string, skipFrames int, printStack bool, severity string, arg interface{}, values map[string]interface{})
}

Output is a log output that can optionally support structured logging

func JsonOutput

func JsonOutput(errorWriter io.Writer, debugWriter io.Writer) Output

JsonOutput creates an output that writes JSON structured log to different io.Writers for errors and debug

func TextOutput

func TextOutput(errorWriter io.Writer, debugWriter io.Writer) Output

TextOutput creates an output that writes text to different io.Writers for errors and debug

func ZapOutput

func ZapOutput(zapLogger *zap.Logger) Output

ZapOutput creates an output that writes using the provided Zap logger

type Severity

type Severity int

Severity is a level of error (higher values are more severe)

func (Severity) String

func (s Severity) String() string