log

package
v0.0.0-...-a858404 Latest Latest
Warning

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

Go to latest
Published: Jan 23, 2024 License: Apache-2.0, MIT Imports: 13 Imported by: 0

Documentation

Overview

Package log implements a library for logging.

This is separate from the standard logging package because logging may be a high-impact activity, and therefore we wanted to provide as much flexibility as possible in the underlying implementation.

Note that logging should still be considered high-impact, and should not be done in the hot path. If necessary, logging statements should be protected with guards regarding the logging level. For example,

if log.IsLogging(log.Debug) {
	log.Debugf(...)
}

This is because the log.Debugf(...) statement alone will generate a significant amount of garbage and churn in many cases, even if no log message is ultimately emitted.

+checkalignedignore

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CopyStandardLogTo

func CopyStandardLogTo(l Level) error

CopyStandardLogTo redirects the stdlib log package global output to the global logger for the specified level.

func Debugf

func Debugf(format string, v ...any)

Debugf logs to the global logger.

func DebugfAtDepth

func DebugfAtDepth(depth int, format string, v ...any)

DebugfAtDepth logs to the global logger.

func Infof

func Infof(format string, v ...any)

Infof logs to the global logger.

func InfofAtDepth

func InfofAtDepth(depth int, format string, v ...any)

InfofAtDepth logs to the global logger.

func IsLogging

func IsLogging(level Level) bool

IsLogging returns whether the global logger is logging.

func LocalStack

func LocalStack(excludeTopN int) []byte

LocalStack returns the local goroutine stack, excluding the top N entries. LocalStack's own entry is excluded by default and does not need to be counted in excludeTopN.

func SetLevel

func SetLevel(newLevel Level)

SetLevel sets the log level.

func SetTarget

func SetTarget(target Emitter)

SetTarget sets the log target.

This is not thread safe and shouldn't be called concurrently with any logging calls.

SetTarget should be called before any instances of log.Log() to avoid race conditions

func Stacks

func Stacks(all bool) []byte

Stacks returns goroutine stacks, like panic.

func Traceback

func Traceback(format string, v ...any)

Traceback logs the given message and dumps a stacktrace of the current goroutine.

This will be print a traceback, tb, as Warningf(format+":\n%s", v..., tb).

func TracebackAll

func TracebackAll(format string, v ...any)

TracebackAll logs the given message and dumps a stacktrace of all goroutines.

This will be print a traceback, tb, as Warningf(format+":\n%s", v..., tb).

func Warningf

func Warningf(format string, v ...any)

Warningf logs to the global logger.

func WarningfAtDepth

func WarningfAtDepth(depth int, format string, v ...any)

WarningfAtDepth logs to the global logger.

Types

type BasicLogger

type BasicLogger struct {
	Level
	Emitter
}

BasicLogger is the default implementation of Logger.

func Log

func Log() *BasicLogger

Log retrieves the global logger.

func (*BasicLogger) Debugf

func (l *BasicLogger) Debugf(format string, v ...any)

Debugf implements logger.Debugf.

func (*BasicLogger) DebugfAtDepth

func (l *BasicLogger) DebugfAtDepth(depth int, format string, v ...any)

DebugfAtDepth logs at a specific depth.

func (*BasicLogger) Infof

func (l *BasicLogger) Infof(format string, v ...any)

Infof implements logger.Infof.

func (*BasicLogger) InfofAtDepth

func (l *BasicLogger) InfofAtDepth(depth int, format string, v ...any)

InfofAtDepth logs at a specific depth.

func (*BasicLogger) IsLogging

func (l *BasicLogger) IsLogging(level Level) bool

IsLogging implements logger.IsLogging.

func (*BasicLogger) SetLevel

func (l *BasicLogger) SetLevel(level Level)

SetLevel sets the logging level.

func (*BasicLogger) Warningf

func (l *BasicLogger) Warningf(format string, v ...any)

Warningf implements logger.Warningf.

func (*BasicLogger) WarningfAtDepth

func (l *BasicLogger) WarningfAtDepth(depth int, format string, v ...any)

WarningfAtDepth logs at a specific depth.

type Emitter

type Emitter interface {
	// Emit emits the given log statement. This allows for control over the
	// timestamp used for logging.
	Emit(depth int, level Level, timestamp time.Time, format string, v ...any)
}

Emitter is the final destination for logs.

type GoogleEmitter

type GoogleEmitter struct {
	*Writer
}

GoogleEmitter is a wrapper that emits logs in a format compatible with package github.com/golang/glog.

func (GoogleEmitter) Emit

func (g GoogleEmitter) Emit(depth int, level Level, timestamp time.Time, format string, args ...any)

Emit emits the message, google-style.

Log lines have this form:

Lmmdd hh:mm:ss.uuuuuu threadid file:line] msg...

where the fields are defined as follows:

L                A single character, representing the log level (eg 'I' for INFO)
mm               The month (zero padded; ie May is '05')
dd               The day (zero padded)
hh:mm:ss.uuuuuu  Time in hours, minutes and fractional seconds
threadid         The space-padded thread ID as returned by GetTID()
file             The file name
line             The line number
msg              The user-supplied message

type JSONEmitter

type JSONEmitter struct {
	*Writer
}

JSONEmitter logs messages in json format.

func (JSONEmitter) Emit

func (e JSONEmitter) Emit(_ int, level Level, timestamp time.Time, format string, v ...any)

Emit implements Emitter.Emit.

type K8sJSONEmitter

type K8sJSONEmitter struct {
	*Writer
}

K8sJSONEmitter logs messages in json format that is compatible with Kubernetes fluent configuration.

func (K8sJSONEmitter) Emit

func (e K8sJSONEmitter) Emit(_ int, level Level, timestamp time.Time, format string, v ...any)

Emit implements Emitter.Emit.

type Level

type Level uint32

Level is the log level.

const (
	// Warning indicates that output should always be emitted.
	Warning Level = iota

	// Info indicates that output should normally be emitted.
	Info

	// Debug indicates that output should not normally be emitted.
	Debug
)

The following levels are fixed, and can never be changed. Since some control RPCs allow for changing the level as an integer, it is only possible to add additional levels, and the existing one cannot be removed.

func (Level) MarshalJSON

func (l Level) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.MarashalJSON.

func (Level) String

func (l Level) String() string

func (*Level) UnmarshalJSON

func (l *Level) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.UnmarshalJSON. It can unmarshal from both string names and integers.

type Logger

type Logger interface {
	// Debugf logs a debug statement.
	Debugf(format string, v ...any)

	// Infof logs at an info level.
	Infof(format string, v ...any)

	// Warningf logs at a warning level.
	Warningf(format string, v ...any)

	// IsLogging returns true iff this level is being logged. This may be
	// used to short-circuit expensive operations for debugging calls.
	IsLogging(level Level) bool
}

Logger is a high-level logging interface. It is in fact, not used within the log package. Rather it is provided for others to provide contextual loggers that may append some addition information to log statement. BasicLogger satisfies this interface, and may be passed around as a Logger.

func BasicRateLimitedLogger

func BasicRateLimitedLogger(every time.Duration) Logger

BasicRateLimitedLogger returns a Logger that logs to the global logger no more than once per the provided duration.

func RateLimitedLogger

func RateLimitedLogger(logger Logger, every time.Duration) Logger

RateLimitedLogger returns a Logger that logs to the provided logger no more than once per the provided duration.

type MultiEmitter

type MultiEmitter []Emitter

MultiEmitter is an emitter that emits to multiple Emitters.

func (*MultiEmitter) Emit

func (m *MultiEmitter) Emit(depth int, level Level, timestamp time.Time, format string, v ...any)

Emit emits to all emitters.

type TestEmitter

type TestEmitter struct {
	TestLogger
}

TestEmitter may be used for wrapping tests.

func (*TestEmitter) Emit

func (t *TestEmitter) Emit(_ int, level Level, timestamp time.Time, format string, v ...any)

Emit emits to the TestLogger.

type TestLogger

type TestLogger interface {
	Logf(format string, v ...any)
}

TestLogger is implemented by testing.T and testing.B.

type Writer

type Writer struct {
	// Next is where output is written.
	Next io.Writer
	// contains filtered or unexported fields
}

Writer writes the output to the given writer.

func (*Writer) Emit

func (l *Writer) Emit(_ int, _ Level, _ time.Time, format string, args ...any)

Emit emits the message.

func (*Writer) Write

func (l *Writer) Write(data []byte) (int, error)

Write writes out the given bytes, handling non-blocking sockets.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL