README
¶
package log
package log provides a minimal interface for structured logging in services.
It may be wrapped to encode conventions, enforce type-safety, etc.
It can be used for both typical application log events, and log-structured data streams.
Rationale
TODO
Usage
Typical application logging.
import (
"os"
"github.com/go-kit/kit/log"
)
func main() {
logger := log.NewLogfmtLogger(os.Stderr)
logger.Log("question", "what is the meaning of life?", "answer", 42)
}
Output:
question="what is the meaning of life?" answer=42
Contextual logging.
func handle(logger log.Logger, req *Request) {
ctx := log.NewContext(logger).With("txid", req.TransactionID, "query", req.Query)
ctx.Log()
answer, err := process(ctx, req.Query)
if err != nil {
ctx.Log("err", err)
return
}
ctx.Log("answer", answer)
}
Output:
txid=12345 query="some=query"
txid=12345 query="some=query" answer=42
Redirect stdlib log to gokit logger.
import (
"os"
stdlog "log"
kitlog "github.com/go-kit/kit/log"
)
func main() {
logger := kitlog.NewJSONLogger(os.Stdout)
stdlog.SetOutput(kitlog.NewStdlibAdapter(logger))
stdlog.Print("I sure like pie")
}
Output
{"msg":"I sure like pie","ts":"2016/01/28 19:41:08"}
Adding a timestamp to contextual logs
func handle(logger log.Logger, req *Request) {
ctx := log.NewContext(logger).With("ts", log.DefaultTimestampUTC, "query", req.Query)
ctx.Log()
answer, err := process(ctx, req.Query)
if err != nil {
ctx.Log("err", err)
return
}
ctx.Log("answer", answer)
}
Output
ts=2016-01-29T00:46:04Z query="some=query"
ts=2016-01-29T00:46:04Z query="some=query" answer=42
Adding caller info to contextual logs
func handle(logger log.Logger, req *Request) {
ctx := log.NewContext(logger).With("caller", log.DefaultCaller, "query", req.Query)
ctx.Log()
answer, err := process(ctx, req.Query)
if err != nil {
ctx.Log("err", err)
return
}
ctx.Log("answer", answer)
}
Output
caller=logger.go:20 query="some=query"
caller=logger.go:28 query="some=query" answer=42
Documentation
¶
Overview ¶
Package log provides basic interfaces for structured logging.
The fundamental interface is Logger. Loggers create log events from key/value data.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // DefaultCaller is a Valuer that returns the file and line where the Log // method was invoked. It can only be used with log.With. DefaultCaller = Caller(3) )
var ErrMissingValue = errors.New("(MISSING)")
ErrMissingValue is appended to keyvals slices with odd length to substitute the missing value.
Functions ¶
func NewStdlibAdapter ¶
func NewStdlibAdapter(logger Logger, options ...StdlibAdapterOption) io.Writer
NewStdlibAdapter returns a new StdlibAdapter wrapper around the passed logger. It's designed to be passed to log.SetOutput.
Types ¶
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
A Context wraps a Logger and holds keyvals that it includes in all log events. When logging, a Context replaces all value elements (odd indexes) containing a Valuer with their generated value for each call to its Log method.
Example ¶
package main
import (
"os"
"github.com/go-kit/kit/log"
)
func main() {
logger := log.NewLogfmtLogger(os.Stdout)
logger.Log("foo", 123)
ctx := log.NewContext(logger).With("level", "info")
ctx.Log()
ctx = ctx.With("msg", "hello")
ctx.Log()
ctx.With("a", 1).Log("b", 2)
}
Output: foo=123 level=info level=info msg=hello level=info msg=hello a=1 b=2
func NewContext ¶
NewContext returns a new Context that logs to logger.
func (*Context) Log ¶
Log replaces all value elements (odd indexes) containing a Valuer in the stored context with their generated value, appends keyvals, and passes the result to the wrapped Logger.
func (*Context) WithPrefix ¶
WithPrefix returns a new Context with keyvals prepended to those of the receiver.
type Logger ¶
type Logger interface {
Log(keyvals ...interface{}) error
}
Logger is the fundamental interface for all log operations. Log creates a log event from keyvals, a variadic sequence of alternating keys and values. Implementations must be safe for concurrent use by multiple goroutines. In particular, any implementation of Logger that appends to keyvals or modifies any of its elements must make a copy first.
func NewJSONLogger ¶
NewJSONLogger returns a Logger that encodes keyvals to the Writer as a single JSON object.
func NewLogfmtLogger ¶
NewLogfmtLogger returns a logger that encodes keyvals to the Writer in logfmt format. The passed Writer must be safe for concurrent use by multiple goroutines if the returned Logger will be used concurrently.
func NewNopLogger ¶
func NewNopLogger() Logger
NewNopLogger returns a logger that doesn't do anything.
type LoggerFunc ¶
type LoggerFunc func(...interface{}) error
LoggerFunc is an adapter to allow use of ordinary functions as Loggers. If f is a function with the appropriate signature, LoggerFunc(f) is a Logger object that calls f.
func (LoggerFunc) Log ¶
func (f LoggerFunc) Log(keyvals ...interface{}) error
Log implements Logger by calling f(keyvals...).
type StdlibAdapter ¶
type StdlibAdapter struct {
Logger
// contains filtered or unexported fields
}
StdlibAdapter wraps a Logger and allows it to be passed to the stdlib logger's SetOutput. It will extract date/timestamps, filenames, and messages, and place them under relevant keys.
type StdlibAdapterOption ¶
type StdlibAdapterOption func(*StdlibAdapter)
StdlibAdapterOption sets a parameter for the StdlibAdapter.
func FileKey ¶
func FileKey(key string) StdlibAdapterOption
FileKey sets the key for the file and line field. By default, it's "file".
func MessageKey ¶
func MessageKey(key string) StdlibAdapterOption
MessageKey sets the key for the actual log message. By default, it's "msg".
func TimestampKey ¶
func TimestampKey(key string) StdlibAdapterOption
TimestampKey sets the key for the timestamp field. By default, it's "ts".
type StdlibWriter ¶
type StdlibWriter struct{}
StdlibWriter implements io.Writer by invoking the stdlib log.Print. It's designed to be passed to a Go kit logger as the writer, for cases where it's necessary to redirect all Go kit log output to the stdlib logger.
If you have any choice in the matter, you shouldn't use this. Prefer to redirect the stdlib log to the Go kit logger via NewStdlibAdapter.
type SwapLogger ¶
type SwapLogger struct {
// contains filtered or unexported fields
}
SwapLogger wraps another logger that may be safely replaced while other goroutines use the SwapLogger concurrently. The zero value for a SwapLogger will discard all log events without error.
SwapLogger serves well as a package global logger that can be changed by importers.
func (*SwapLogger) Log ¶
func (l *SwapLogger) Log(keyvals ...interface{}) error
Log implements the Logger interface by forwarding keyvals to the currently wrapped logger. It does not log anything if the wrapped logger is nil.
func (*SwapLogger) Swap ¶
func (l *SwapLogger) Swap(logger Logger)
Swap replaces the currently wrapped logger with logger. Swap may be called concurrently with calls to Log from other goroutines.
type Valuer ¶
type Valuer func() interface{}
A Valuer generates a log value. When passed to Context.With in a value element (odd indexes), it represents a dynamic value which is re-evaluated with each log event.
var ( // DefaultTimestamp is a Valuer that returns the current wallclock time, // respecting time zones, when bound. DefaultTimestamp Valuer = func() interface{} { return time.Now().Format(time.RFC3339) } // DefaultTimestampUTC is a Valuer that returns the current time in UTC // when bound. DefaultTimestampUTC Valuer = func() interface{} { return time.Now().UTC().Format(time.RFC3339) } )
Source Files
Directories