sallustkit

Documentation

Overview

Package sallustkit provides an adapter layer between go.uber.org/zap logging and the variadic approach in go-kit.

Index

• Constants
• type LogMethod
  • func LogMethodFor(l *zap.Logger, v level.Value) (lm LogMethod)
• type Logger
  • func (l Logger) Log(keyvals ...interface{}) error

Examples

• Logger
• Logger (Custom)

Constants

const (
	// NotAString is used in log output when a key or value which should
	// have been a string was not a string.
	NotAString = "(NOT A STRING)"

	// NoLogMessage is used as the log message when no message could be
	// found in the go-kit keyvals.
	NoLogMessage = "No log message found"

	// DefaultMessageKey is the key assumed to hold the log message when no
	// MessageKey is set.  This is used when parsing go-kit Log keyvals.
	//
	// NOTE: This is not the same as the key used by zap to output the message
	// in its log output.  That is controlled by the zap configuration, which
	// may be a sallust.Config.
	DefaultMessageKey = "msg"
)

Types

type LogMethod

type LogMethod func(string, ...zap.Field)

LogMethod refers to a method of a zap Logger. Used to define which method should received go-kit leveled logging, e.g. Error, Info, etc.

func LogMethodFor

func LogMethodFor(l *zap.Logger, v level.Value) (lm LogMethod)

LogMethodFor returns the method of a zap Logger that corresponds to a given go-kit level. If v is unrecognized, l.Error is returned. This function never returns nil.

type Logger

type Logger struct {
	// Zap is the zap Logger to which output is sent.  This field is required,
	// and Log will panic if it is not set.
	Zap *zap.Logger

	// MessageKey is the go-kit logging key which holds the log message.
	// If unset, DefaultMessageKey is used.
	//
	// This key is used to pull out the message so that it can be passed
	// as the first argument to a zap logger's method, e.g. Error, Info, etc.
	MessageKey string

	// DefaultLevel is the go-kit level to use when no level
	// is supplied in the keyvals.  If unset, Error is used.
	DefaultLevel level.Value
}

Logger is a go-kit logger that adapts its output onto a zap logger.

Example

l := Logger{
	Zap: zap.NewExample(),
}

l.Log("msg", "hello, world!", "duration", 15*time.Second)
l.Log("msg", "this entry supplies a level", "value", 123, "this key doesn't matter", level.DebugValue())

Output:

{"level":"error","msg":"hello, world!","duration":"15s"}
{"level":"debug","msg":"this entry supplies a level","value":123}

Example (Custom)

l := Logger{
	Zap:          zap.NewExample(),
	MessageKey:   "message",
	DefaultLevel: level.InfoValue(),
}

// the message will still be output to whatever zap is configured with
l.Log("message", "hello, world!", "duration", 15*time.Second)

// override the DefaultLevel with what's passed to Log
l.Log("message", "this entry supplies a level", "value", 123, "this key doesn't matter", level.DebugValue())

Output:

{"level":"info","msg":"hello, world!","duration":"15s"}
{"level":"debug","msg":"this entry supplies a level","value":123}

func (Logger) Log

func (l Logger) Log(keyvals ...interface{}) error

Log accepts key/value pairs in the typical go-kit fashion and parses them to use with the configured zap logger. This method always returns nil. If keyvals is empty, then this method returns with no output.

Each key/value pair is examined and used to build up a method call to the configured zap logger using the following basic steps:

• Any key that is not a string results in a NotAString key in the zap output

• If keyvals is of odd length, then the last key is emitted as a zap.NamedError with the value of go-kit's log.ErrMissingValue.

• The value for any key that equals the configured MessageKey (or, DefaultMessageKey if that field is unset) is used as the first parameter to the zap logger method.

• Any value that is a defined go-kit level.Value is used to determine which zap logger method is invoked, e.g. level.DebugValue() results in the Debug method, etc. In this case, the associated key is ignored.

• Any key/value not matching the above steps is passed to the zap logger method as a zap.Any field.

Examples:

given:

l, _ := zap.NewDevelopment() // or any *zap.Logger
gokit := sallustkit.Logger{
  Zap: l,
  // take the defaults for the other fields
}

then:

this:     gokit.Log("msg", "hi there", "value", 123)
becomes:  l.Error("hi there", zap.Any("value", 123)) // defaults to error, change this by setting go-kit.DefaultLevel

this:     gokit.Log("msg", "more values", "name1", "value1", "name2", 45.6)
becomes:  l.Error("more values", zap.Any("name1", "value1"), zap.Any("name2", 45.6))

this:     gokit.Log(level.Key(), level.InfoValue(), "value", 123)
becomes:  l.Info("No log message found", zap.Any("value", 123))

this:     gokit.Log("msg", "hi there", "this key doesn't matter", level.DebugValue())
becomes:  l.Debug("hi there") // if a value is a go-kit level.Value, the key is ignored