|
|
@@ -14,6 +14,27 @@
|
|
|
limitations under the License.
|
|
|
*/
|
|
|
|
|
|
+// Package log provides types and functions related to logging, passing
|
|
|
+// loggers through a context, and attaching context to the logger.
|
|
|
+//
|
|
|
+// # Transitional types
|
|
|
+//
|
|
|
+// This package contains various types that are aliases for types in [logrus].
|
|
|
+// These aliases are intended for transitioning away from hard-coding logrus
|
|
|
+// as logging implementation. Consumers of this package are encouraged to use
|
|
|
+// the type-aliases from this package instead of directly using their logrus
|
|
|
+// equivalent.
|
|
|
+//
|
|
|
+// The intent is to replace these aliases with locally defined types and
|
|
|
+// interfaces once all consumers are no longer directly importing logrus
|
|
|
+// types.
|
|
|
+//
|
|
|
+// IMPORTANT: due to the transitional purpose of this package, it is not
|
|
|
+// guaranteed for the full logrus API to be provided in the future. As
|
|
|
+// outlined, these aliases are provided as a step to transition away from
|
|
|
+// a specific implementation which, as a result, exposes the full logrus API.
|
|
|
+// While no decisions have been made on the ultimate design and interface
|
|
|
+// provided by this package, we do not expect carrying "less common" features.
|
|
|
package log
|
|
|
|
|
|
import (
|
|
|
@@ -23,98 +44,139 @@ import (
|
|
|
"github.com/sirupsen/logrus"
|
|
|
)
|
|
|
|
|
|
-var (
|
|
|
- // G is an alias for GetLogger.
|
|
|
- //
|
|
|
- // We may want to define this locally to a package to get package tagged log
|
|
|
- // messages.
|
|
|
- G = GetLogger
|
|
|
+// G is a shorthand for [GetLogger].
|
|
|
+//
|
|
|
+// We may want to define this locally to a package to get package tagged log
|
|
|
+// messages.
|
|
|
+var G = GetLogger
|
|
|
+
|
|
|
+// L is an alias for the standard logger.
|
|
|
+var L = &Entry{
|
|
|
+ Logger: logrus.StandardLogger(),
|
|
|
+ // Default is three fields plus a little extra room.
|
|
|
+ Data: make(Fields, 6),
|
|
|
+}
|
|
|
|
|
|
- // L is an alias for the standard logger.
|
|
|
- L = logrus.NewEntry(logrus.StandardLogger())
|
|
|
-)
|
|
|
+type loggerKey struct{}
|
|
|
|
|
|
-type (
|
|
|
- loggerKey struct{}
|
|
|
+// Fields type to pass to "WithFields".
|
|
|
+type Fields = map[string]any
|
|
|
|
|
|
- // Fields type to pass to `WithFields`, alias from `logrus`.
|
|
|
- Fields = logrus.Fields
|
|
|
+// Entry is a logging entry. It contains all the fields passed with
|
|
|
+// [Entry.WithFields]. It's finally logged when Trace, Debug, Info, Warn,
|
|
|
+// Error, Fatal or Panic is called on it. These objects can be reused and
|
|
|
+// passed around as much as you wish to avoid field duplication.
|
|
|
+//
|
|
|
+// Entry is a transitional type, and currently an alias for [logrus.Entry].
|
|
|
+type Entry = logrus.Entry
|
|
|
|
|
|
- // Level is a logging level
|
|
|
- Level = logrus.Level
|
|
|
-)
|
|
|
+// RFC3339NanoFixed is [time.RFC3339Nano] with nanoseconds padded using
|
|
|
+// zeros to ensure the formatted time is always the same number of
|
|
|
+// characters.
|
|
|
+const RFC3339NanoFixed = "2006-01-02T15:04:05.000000000Z07:00"
|
|
|
+
|
|
|
+// Level is a logging level.
|
|
|
+type Level = logrus.Level
|
|
|
|
|
|
+// Supported log levels.
|
|
|
const (
|
|
|
- // RFC3339NanoFixed is time.RFC3339Nano with nanoseconds padded using zeros to
|
|
|
- // ensure the formatted time is always the same number of characters.
|
|
|
- RFC3339NanoFixed = "2006-01-02T15:04:05.000000000Z07:00"
|
|
|
+ // TraceLevel level. Designates finer-grained informational events
|
|
|
+ // than [DebugLevel].
|
|
|
+ TraceLevel Level = logrus.TraceLevel
|
|
|
|
|
|
- // TextFormat represents the text logging format
|
|
|
- TextFormat = "text"
|
|
|
+ // DebugLevel level. Usually only enabled when debugging. Very verbose
|
|
|
+ // logging.
|
|
|
+ DebugLevel Level = logrus.DebugLevel
|
|
|
|
|
|
- // JSONFormat represents the JSON logging format
|
|
|
- JSONFormat = "json"
|
|
|
+ // InfoLevel level. General operational entries about what's going on
|
|
|
+ // inside the application.
|
|
|
+ InfoLevel Level = logrus.InfoLevel
|
|
|
|
|
|
- // TraceLevel level.
|
|
|
- TraceLevel = logrus.TraceLevel
|
|
|
+ // WarnLevel level. Non-critical entries that deserve eyes.
|
|
|
+ WarnLevel Level = logrus.WarnLevel
|
|
|
|
|
|
- // DebugLevel level.
|
|
|
- DebugLevel = logrus.DebugLevel
|
|
|
+ // ErrorLevel level. Logs errors that should definitely be noted.
|
|
|
+ // Commonly used for hooks to send errors to an error tracking service.
|
|
|
+ ErrorLevel Level = logrus.ErrorLevel
|
|
|
|
|
|
- // InfoLevel level.
|
|
|
- InfoLevel = logrus.InfoLevel
|
|
|
+ // FatalLevel level. Logs and then calls "logger.Exit(1)". It exits
|
|
|
+ // even if the logging level is set to Panic.
|
|
|
+ FatalLevel Level = logrus.FatalLevel
|
|
|
+
|
|
|
+ // PanicLevel level. This is the highest level of severity. Logs and
|
|
|
+ // then calls panic with the message passed to Debug, Info, ...
|
|
|
+ PanicLevel Level = logrus.PanicLevel
|
|
|
)
|
|
|
|
|
|
-// SetLevel sets log level globally.
|
|
|
+// SetLevel sets log level globally. It returns an error if the given
|
|
|
+// level is not supported.
|
|
|
+//
|
|
|
+// level can be one of:
|
|
|
+//
|
|
|
+// - "trace" ([TraceLevel])
|
|
|
+// - "debug" ([DebugLevel])
|
|
|
+// - "info" ([InfoLevel])
|
|
|
+// - "warn" ([WarnLevel])
|
|
|
+// - "error" ([ErrorLevel])
|
|
|
+// - "fatal" ([FatalLevel])
|
|
|
+// - "panic" ([PanicLevel])
|
|
|
func SetLevel(level string) error {
|
|
|
lvl, err := logrus.ParseLevel(level)
|
|
|
if err != nil {
|
|
|
return err
|
|
|
}
|
|
|
|
|
|
- logrus.SetLevel(lvl)
|
|
|
+ L.Logger.SetLevel(lvl)
|
|
|
return nil
|
|
|
}
|
|
|
|
|
|
// GetLevel returns the current log level.
|
|
|
func GetLevel() Level {
|
|
|
- return logrus.GetLevel()
|
|
|
+ return L.Logger.GetLevel()
|
|
|
}
|
|
|
|
|
|
-// SetFormat sets log output format
|
|
|
-func SetFormat(format string) error {
|
|
|
+// OutputFormat specifies a log output format.
|
|
|
+type OutputFormat string
|
|
|
+
|
|
|
+// Supported log output formats.
|
|
|
+const (
|
|
|
+ // TextFormat represents the text logging format.
|
|
|
+ TextFormat OutputFormat = "text"
|
|
|
+
|
|
|
+ // JSONFormat represents the JSON logging format.
|
|
|
+ JSONFormat OutputFormat = "json"
|
|
|
+)
|
|
|
+
|
|
|
+// SetFormat sets the log output format ([TextFormat] or [JSONFormat]).
|
|
|
+func SetFormat(format OutputFormat) error {
|
|
|
switch format {
|
|
|
case TextFormat:
|
|
|
- logrus.SetFormatter(&logrus.TextFormatter{
|
|
|
+ L.Logger.SetFormatter(&logrus.TextFormatter{
|
|
|
TimestampFormat: RFC3339NanoFixed,
|
|
|
FullTimestamp: true,
|
|
|
})
|
|
|
+ return nil
|
|
|
case JSONFormat:
|
|
|
- logrus.SetFormatter(&logrus.JSONFormatter{
|
|
|
+ L.Logger.SetFormatter(&logrus.JSONFormatter{
|
|
|
TimestampFormat: RFC3339NanoFixed,
|
|
|
})
|
|
|
+ return nil
|
|
|
default:
|
|
|
return fmt.Errorf("unknown log format: %s", format)
|
|
|
}
|
|
|
-
|
|
|
- return nil
|
|
|
}
|
|
|
|
|
|
// WithLogger returns a new context with the provided logger. Use in
|
|
|
// combination with logger.WithField(s) for great effect.
|
|
|
-func WithLogger(ctx context.Context, logger *logrus.Entry) context.Context {
|
|
|
- e := logger.WithContext(ctx)
|
|
|
- return context.WithValue(ctx, loggerKey{}, e)
|
|
|
+func WithLogger(ctx context.Context, logger *Entry) context.Context {
|
|
|
+ return context.WithValue(ctx, loggerKey{}, logger.WithContext(ctx))
|
|
|
}
|
|
|
|
|
|
// GetLogger retrieves the current logger from the context. If no logger is
|
|
|
// available, the default logger is returned.
|
|
|
-func GetLogger(ctx context.Context) *logrus.Entry {
|
|
|
- logger := ctx.Value(loggerKey{})
|
|
|
-
|
|
|
- if logger == nil {
|
|
|
- return L.WithContext(ctx)
|
|
|
+func GetLogger(ctx context.Context) *Entry {
|
|
|
+ if logger := ctx.Value(loggerKey{}); logger != nil {
|
|
|
+ return logger.(*Entry)
|
|
|
}
|
|
|
-
|
|
|
- return logger.(*logrus.Entry)
|
|
|
+ return L.WithContext(ctx)
|
|
|
}
|
Sebastiaan van Stijn