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 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 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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewTestContext ¶
NewTestContext 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".
func StdLogger ¶
StdLogger returns a stdlib *log.Logger that uses the Logger associated with ctx and logs at the specified loglevel.
Avoid using this functions 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).
Types ¶
type LogLevel ¶
type LogLevel uint32
LogLevel is an abstracted common log-level type for 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 )
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!
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.
Source Files