log

Documentation

Overview

Package log provides global logging functions to be used throughout the charon app. It supports contextual logging via WithCtx and structured logging and structured errors via z.Field.

Index

• func CopyFields(target context.Context, source context.Context) context.Context
• func Debug(ctx context.Context, msg string, fields ...z.Field)
• func Error(ctx context.Context, msg string, err error, fields ...z.Field)
• func Filter(opts ...FilterOption) z.Field
• func Info(ctx context.Context, msg string, fields ...z.Field)
• func InitConsoleForT(_ *testing.T, ws zapcore.WriteSyncer, opts ...func(*zapcore.EncoderConfig))
• func InitJSONForT(t *testing.T, ws zapcore.WriteSyncer, opts ...func(*zapcore.EncoderConfig))
• func InitLogfmtForT(t *testing.T, ws zapcore.WriteSyncer, opts ...func(*zapcore.EncoderConfig))
• func InitLogger(config Config) error
• func Stop(ctx context.Context)
• func Warn(ctx context.Context, msg string, err error, fields ...z.Field)
• func WithCtx(ctx context.Context, fields ...z.Field) context.Context
• func WithTopic(ctx context.Context, component string) context.Context
• type Config
  • func DefaultConfig() Config
  • func (c Config) ZapLevel() (zapcore.Level, error)
• type FilterOption
  • func WithFilterRateLimit(limit rate.Limit) FilterOption

Functions

func CopyFields

func CopyFields(target context.Context, source context.Context) context.Context

CopyFields returns a copy of the target with which the logging fields of the source context are associated.

func Debug

func Debug(ctx context.Context, msg string, fields ...z.Field)

Debug logs the message and fields (incl fields in the context) at Debug level. Debug should be used for most logging.

func Error

func Error(ctx context.Context, msg string, err error, fields ...z.Field)

Error wraps err with msg and fields and logs it (incl fields in the context) at Error level. Nil err is supported and results in similar behaviour to Info, just at Error level. Error should only be used when a problem is encountered that *does* require action to be taken.

func Filter

func Filter(opts ...FilterOption) z.Field

Filter returns a stateful structure logging field that results in logs lines being dropped if internal rate limit is exceeded. Usage:

filter := log.Filter()
for event := range eventPipe() {
  err := process(event)
  if err != nil {
    log.Error(ctx, "This error should only be logged max once an hour", err, filter)
  }
}

func Info

func Info(ctx context.Context, msg string, fields ...z.Field)

Info logs the message and fields (incl fields in the context) at Info level. Info should only be used for high level important events.

func InitConsoleForT

func InitConsoleForT(_ *testing.T, ws zapcore.WriteSyncer, opts ...func(*zapcore.EncoderConfig))

InitConsoleForT initialises a console logger for testing purposes.

func InitJSONForT

func InitJSONForT(t *testing.T, ws zapcore.WriteSyncer, opts ...func(*zapcore.EncoderConfig))

InitJSONForT initialises a json logger for testing purposes.

func InitLogfmtForT

func InitLogfmtForT(t *testing.T, ws zapcore.WriteSyncer, opts ...func(*zapcore.EncoderConfig))

InitLogfmtForT initialises a logfmt logger for testing purposes.

func InitLogger

func InitLogger(config Config) error

InitLogger initialises the global logger based on the provided config.

func Stop

func Stop(ctx context.Context)

Stop stops all log processors.

func Warn

func Warn(ctx context.Context, msg string, err error, fields ...z.Field)

Warn wraps err with msg and fields and logs it (incl fields in the context) at Warn level. Nil err is supported and results in similar behaviour to Info, just at Warn level. Warn should only be used when a problem is encountered that *does not* require any action to be taken.

func WithCtx

func WithCtx(ctx context.Context, fields ...z.Field) context.Context

WithCtx returns a copy of the context with which the logging fields are associated. Usage:

ctx := log.WithCtx(ctx, z.Int("slot", 1234))
...
log.Info(ctx, "Slot processed") // Will contain field: slot=1234

func WithTopic

func WithTopic(ctx context.Context, component string) context.Context

WithTopic is a convenience function that adds the topic contextual logging field to the returned child context.

Types

type Config

type Config struct {
	Level         string   // debug, info, warn or error
	Format        string   // console or json
	LokiAddresses []string // URLs for loki logging spout
	LokiService   string   // Value of the service label pushed with loki logs.
}

Config defines the logging configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the default logging config.

func (Config) ZapLevel

func (c Config) ZapLevel() (zapcore.Level, error)

ZapLevel returns the zapcore level.

type FilterOption

type FilterOption func(*filter)

func WithFilterRateLimit

func WithFilterRateLimit(limit rate.Limit) FilterOption

WithFilterRateLimit returns a filter option that rate limits logging by a per second limit.