log

Documentation

Overview

Package log sets up a shared logger that can be used by all packages run under one binary.

This package wraps zap very lightly so zap best practices apply here too, namely use `With` for KV pairs to add context to a line. The lack of a wide gamut of logging levels is by design. The intended use case for each of the levels are:

Error:
  Logs a message as an error, may also have external side effects such as posting to rollbar, sentry or alerting directly.
Info:
  Used for production.
  Context should all be in K=V pairs so they can be useful to ops and future-you-at-3am.
Debug:
  Meant for developer use *during development*.

Index

• func ContextWithLogger(ctx context.Context, logger Logger) context.Context
• func ProtoAsJSON(message proto.Message) json.Marshaler
• type Logger
  • func GetLogger(ctx context.Context) Logger
  • func Init(service string) (Logger, error)
  • func Test(t zaptest.TestingT, service string) Logger
  • func (l Logger) AddCallerSkip(skip int) Logger
  • func (l Logger) Close()
  • func (l Logger) Debug(args ...interface{})
  • func (l Logger) Error(err error, args ...interface{})
  • func (l Logger) Fatal(err error, args ...interface{})
  • func (l Logger) GRPCLoggers() (grpc.StreamServerInterceptor, grpc.UnaryServerInterceptor)
  • func (l Logger) Info(args ...interface{})
  • func (l Logger) Package(pkg string) Logger
  • func (l Logger) With(args ...interface{}) Logger

Examples

• Logger.Debug
• Logger.Error
• Logger.Fatal
• Logger.Info
• Logger.Package
• Logger.With

Functions

func ContextWithLogger

func ContextWithLogger(ctx context.Context, logger Logger) context.Context

ContextWithLogger returns a copy of parent in which the logger is embedded.

func ProtoAsJSON

func ProtoAsJSON(message proto.Message) json.Marshaler

ProtoAsJSON performs a type erasure of proto.Message to be embedded into the log fields.

This is a workaround for types generated by protobuf providing a String() method. This makes them interpreted by the logger as fmt.Stringer interfaces, and flattened to string, rather than, as one would expect, a JSON object.

Example:

logger = logger.With("my-proto-object", log.ProtoAsJSON(&myProto))

Types

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger is a wrapper around zap.SugaredLogger

func GetLogger

func GetLogger(ctx context.Context) Logger

GetLogger returns the logger associated with this context, or no-op logger if no logger is embedded with key.

func Init

func Init(service string) (Logger, error)

Init initializes the logging system and sets the "service" key to the provided argument. This func should only be called once and after flag.Parse() has been called otherwise leveled logging will not be configured correctly.

func Test

func Test(t zaptest.TestingT, service string) Logger

Test returns a logger that does not log to rollbar and can be used with testing.TB to only log on test failure or run with -v

func (Logger) AddCallerSkip

func (l Logger) AddCallerSkip(skip int) Logger

AddCallerSkip increases the number of callers skipped by caller annotation. When building wrappers around the Logger, supplying this option prevents Logger from always reporting the wrapper code as the caller.

func (Logger) Close

func (l Logger) Close()

Close finishes and flushes up any in-flight logs

func (Logger) Debug

func (l Logger) Debug(args ...interface{})

Debug is used to log messages in development, not even for lab. No one cares what you pass to Debug. All the values of arg are stringified and concatenated without any strings.

Example

l := setupForExamples("debug")
defer l.Close()

l.Debug("debug message")

Output:

{"level":"debug","caller":"log/log_examples_test.go:36","msg":"debug message","service":"github.com/packethost/pkg","pkg":"debug"}

func (Logger) Error

func (l Logger) Error(err error, args ...interface{})

Error is used to log an error, the error will be forwared to rollbar and/or other external services. All the values of arg are stringified and concatenated without any space. If no args are provided err.Error() is used as the log message.

Example

l := setupForExamples("error")
defer l.Close()

l.Error(fmt.Errorf("oh no an error"))

Output:

{"level":"error","caller":"log/log_examples_test.go:59","msg":"oh no an error","service":"github.com/packethost/pkg","pkg":"error","error":"oh no an error"}

func (Logger) Fatal

func (l Logger) Fatal(err error, args ...interface{})

Fatal calls Error followed by a panic(err)

Example

l := setupForExamples("fatal")
defer l.Close()

defer func() {
	_ = recover()
}()
l.Fatal(fmt.Errorf("oh no an error"))

Output:

{"level":"error","caller":"log/log_examples_test.go:72","msg":"oh no an error","service":"github.com/packethost/pkg","pkg":"fatal","error":"oh no an error"}

func (Logger) GRPCLoggers

func (l Logger) GRPCLoggers() (grpc.StreamServerInterceptor, grpc.UnaryServerInterceptor)

GRPCLoggers returns server side logging middleware for gRPC servers

func (Logger) Info

func (l Logger) Info(args ...interface{})

Info is used to log message in production, only simple strings should be given in the args. Context should be added as K=V pairs using the `With` method. All the values of arg are stringified and concatenated without any strings.

Example

l := setupForExamples("info")
defer l.Close()

defer func() {
	_ = recover()
}()
l.Info("info message")

Output:

{"level":"info","caller":"log/log_examples_test.go:49","msg":"info message","service":"github.com/packethost/pkg","pkg":"info"}

func (Logger) Package

func (l Logger) Package(pkg string) Logger

Package returns a copy of the logger with the "pkg" set to the argument. It should be called before the original Logger has had any keys set to values, otherwise confusion may ensue.

Example

l := setupForExamples("info")
defer l.Close()

l.Info("info message")
l = l.Package("package")
l.Info("info message")

Output:

{"level":"info","caller":"log/log_examples_test.go:92","msg":"info message","service":"github.com/packethost/pkg","pkg":"info"}
{"level":"info","caller":"log/log_examples_test.go:94","msg":"info message","service":"github.com/packethost/pkg","pkg":"info","pkg":"package"}

func (Logger) With

func (l Logger) With(args ...interface{}) Logger

With is used to add context to the logger, a new logger copy with the new K=V pairs as context is returned.

Example

l := setupForExamples("with")
defer l.Close()

l.With("true", true).Info("info message")

Output:

{"level":"info","caller":"log/log_examples_test.go:82","msg":"info message","service":"github.com/packethost/pkg","pkg":"with","true":true}