log

package
v0.0.0-...-bd0cbf8 Latest Latest
Warning

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

 Go to latest Published: Dec 13, 2024 License: Apache-2.0, MIT Imports: 13 Imported by: 258

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(depth 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(depth 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.

Source Files

View all Source files

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.