Documentation
¶
Overview ¶
Package dlog implements a generic logger facade.
There are three first-class things of value in this package:
First: The Logger interface. This is a simple structured logging interface that is mostly trivial to implement on top of most logging backends, and allows library code to not need to care about what specific logging system the calling program uses.
Second: The WithLogger and WithField functions for affecting the logging for a context.
Third: The actual logging functions. If you are writing library code and want to log things, then you should take a context.Context as an argument, and then call dlog.{Level}{,f,ln}(ctx, args) to log.
Index ¶
- func Debug(ctx context.Context, args ...interface{})
- func Debugf(ctx context.Context, format string, args ...interface{})
- func Debugln(ctx context.Context, args ...interface{})
- func DefaultFieldSort(fieldNames []string)
- func Error(ctx context.Context, args ...interface{})
- func Errorf(ctx context.Context, format string, args ...interface{})
- func Errorln(ctx context.Context, args ...interface{})
- func Info(ctx context.Context, args ...interface{})
- func Infof(ctx context.Context, format string, args ...interface{})
- func Infoln(ctx context.Context, args ...interface{})
- func Log(ctx context.Context, lvl LogLevel, args ...interface{})
- func Logf(ctx context.Context, lvl LogLevel, format string, args ...interface{})
- func Logln(ctx context.Context, lvl LogLevel, args ...interface{})
- func NewTestContext(t testing.TB, failOnError bool) context.Context
- func NewTestContextWithOpts(t testing.TB, opts ...TestContextOption) context.Context
- func Print(ctx context.Context, args ...interface{})
- func Printf(ctx context.Context, format string, args ...interface{})
- func Println(ctx context.Context, args ...interface{})
- func SetFallbackLogger(l Logger)
- func StdLogger(ctx context.Context, level LogLevel) *log.Logger
- func Trace(ctx context.Context, args ...interface{})
- func Tracef(ctx context.Context, format string, args ...interface{})
- func Traceln(ctx context.Context, args ...interface{})
- func Warn(ctx context.Context, args ...interface{})
- func Warnf(ctx context.Context, format string, args ...interface{})
- func Warning(ctx context.Context, args ...interface{})
- func Warningf(ctx context.Context, format string, args ...interface{})
- func Warningln(ctx context.Context, args ...interface{})
- func Warnln(ctx context.Context, args ...interface{})
- func WithField(ctx context.Context, key string, value interface{}) context.Context
- func WithLogger(ctx context.Context, logger Logger) context.Context
- type LogLevel
- type Logger
- type LoggerWithMaxLevel
- type OptimizedLogger
- type TestContextOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultFieldSort ¶ added in v1.2.3
func DefaultFieldSort(fieldNames []string)
DefaultFieldSort is the field sorter that is used by the default fallback logger. It mostly mimics the logrus defaults. This function may go away if we change the default fallback logger.
func NewTestContext ¶
NewTestContext is like NewTestContextWithOpts but allows for the failOnError option to be set as a boolean. It is kept for backward-compatibility, new code should prefer NewTestContextWithOpts
func NewTestContextWithOpts ¶ added in v1.2.2
func NewTestContextWithOpts(t testing.TB, opts ...TestContextOption) context.Context
NewTestContextWithOpts takes a testing.TB (that is: either a *testing.T or a *testing.B) and returns a good default Context to use in unit test. The Context will have dlog configured to log using the Go test runner's built-in logging facilities. The context will be canceled when the test terminates. The failOnError argument controls whether calling any of the dlog.Error{,f,ln} functions should cause the test to fail.
Naturally, you should only use this from inside of your *_test.go files.
func SetFallbackLogger ¶
func SetFallbackLogger(l Logger)
SetFallbackLogger sets the Logger that is returned for a context that doesn't have a Logger associated with it. A nil fallback Logger will cause dlog calls on a context without a Logger to panic, which would be good for detecting places where contexts are not passed around correctly. However, the default fallback logger is Logrus and will behave reasonably; in order to make using dlog a safe "no brainer".
If the logger implements OptimizedLogger, then dlog will take advantage of that.
func StdLogger ¶
StdLogger returns a stdlib *log.Logger that uses the Logger associated with ctx and logs at the specified loglevel.
Avoid using this function if at all possible; prefer to use the {Trace,Debug,Info,Print,Warn,Error}{f,ln,}() functions. You should only use this for working with external libraries that demand a stdlib *log.Logger.
func WithField ¶
WithField returns a copy of ctx with the logger field key=value associated with it, for future calls to {Trace,Debug,Info,Print,Warn,Error}{f,ln,}() and StdLogger().
func WithLogger ¶
WithLogger returns a copy of ctx with logger associated with it, for future calls to {Trace,Debug,Info,Print,Warn,Error}{f,ln,}() and StdLogger().
You should only really ever call WithLogger from the initial process set up (i.e. directly inside your 'main()' function).
If the logger implements OptimizedLogger, then dlog will take advantage of that.
Types ¶
type LogLevel ¶
type LogLevel uint32
LogLevel is an abstracted common log-level type for Logger.StdLogger().
const ( // LogLevelError is for errors that should definitely be noted. LogLevelError LogLevel = iota // LogLevelWarn is for non-critical entries that deserve eyes. LogLevelWarn // LogLevelInfo is for general operational entries about what's // going on inside the application. LogLevelInfo // LogLevelDebug is for debugging. Very verbose logging. LogLevelDebug // LogLevelTrace is for extreme debugging. Even finer-grained // informational events than the Debug. LogLevelTrace )
func MaxLogLevel ¶ added in v1.3.1
MaxLogLevel returns the maximum loglevel of the Logger associated with the ctx if that logger implements the LoggerWithMaxLevel interface, or the highest possible level (LogLevelTrace) if it doesn't.
type Logger ¶
type Logger interface {
// Helper marks the calling function as a logging helper
// function. This way loggers can report the line that the
// log came from, while excluding functions that are part of
// dlog itself.
//
// See also: testing.T.Helper
Helper()
// WithField returns a copy of the logger with the
// structured-logging field key=value associated with it, for
// future calls to .Log().
WithField(key string, value interface{}) Logger
// StdLogger returns a stdlib *log.Logger that writes to this
// Logger at the specified loglevel; for use with external
// libraries that demand a stdlib *log.Logger. Since
StdLogger(LogLevel) *log.Logger
// Log actually logs a message.
Log(level LogLevel, msg string)
}
Logger is a generic logging interface that most loggers implement, so that consumers don't need to care about the actual log implementation.
Note that unlike logrus.FieldLogger, it does not include Fatal or Panic logging options. Do proper error handling! Return those errors!
Because this interface cannot change without breaking backward compatibility, it is frozen and cannot be changed.
func WrapLogrus ¶
WrapLogrus converts a logrus *Logger into a generic Logger.
You should only really ever call WrapLogrus from the initial process set up (i.e. directly inside your 'main()' function), and you should pass the result directly to WithLogger.
func WrapTB ¶
WrapTB converts a testing.TB (that is: either a *testing.T or a *testing.B) into a generic Logger.
Naturally, you should only use this from inside of your *_test.go files. The failOnError argument controls whether calling any of the dlog.Error{,f,ln} functions should cause the test to fail.
This is considered deprecated; you should consider using NewTestContext (which calls this) instead.
type LoggerWithMaxLevel ¶ added in v1.3.1
type LoggerWithMaxLevel interface {
// MaxLevel return the maximum loglevel that will be logged
MaxLevel() LogLevel
}
LoggerWithMaxLevel can be implemented by loggers that define a maximum level that will be logged, e.g. if a logger defines a max-level of LogLevelInfo, then only LogLevelError, LogLevelWarn, and LogLevelInfo will be logged; while LogLevelDebug and LogLevelTrace will be discarded.
This interface can be used for examining what the loggers max level is so that resource consuming string formatting can be avoided if its known that the resulting message will be discarded anyway.
The MaxLevel method is provided in an extra interface for two reasons:
1. Expected implementations of OptimizedLogger that don't need a MaxLevel, such as a wrapper for log.Logger.
2. A concern about performance degradation in existing implementations when checks like:
if opt, ok := l.(OptimizedLogger); ok {
...
}
no longer detect implementations that lack the MaxLevel method and silently choose a non-optimized approach.
type OptimizedLogger ¶ added in v1.2.5
type OptimizedLogger interface {
Logger
// UnformattedLog formats then logs a message. The message is
// formatted using the default formats for its operands and
// adds spaces between operands when neither is a string; in
// the manner of fmt.Print().
UnformattedLog(level LogLevel, args ...interface{})
// UnformattedLogln formats then logs a message. The message
// is formatted using the default formats for its operands and
// always adds spaces between operands; in the manner of
// fmt.Println() but without appending a newline.
UnformattedLogln(level LogLevel, args ...interface{})
// UnformattedLogf formats then logs a message. The message is
// formatted according to the format specifier; in the manner
// of fmt.Printf().
UnformattedLogf(level LogLevel, format string, args ...interface{})
}
OptimizedLogger is a Logger that takes on the complexity of formatting log lines in to a string. Normally this is done by dlog itself before passing the formatted string to the Logger. However, if the Logger is able to do these things itself then it might save some time by not actually formatting messages that won't be printed.
Because OptimizedLogger is an opt-in optimization that does not affect correctness, its definition may change between dlib versions.
type TestContextOption ¶ added in v1.2.2
type TestContextOption func(*tbWrapper)
TestContextOption represents options that can be set on test contexts
func WithFailOnError ¶ added in v1.2.2
func WithFailOnError(failOnError bool) TestContextOption
WithFailOnError sets a test context to fail on calling any of the dlog.Error{,f,ln} functions. If not given, defaults to false
func WithTimestampLogging ¶ added in v1.2.2
func WithTimestampLogging(logTimestamps bool) TestContextOption
WithTimestampLogging sets a test context to always log timestamps Note that these will be logged as log fields. If not given, defaults to true
Source Files