clzap

Documentation

Overview

Package clzap provides logging using the zap logging library

Index

• Variables
• func Fx() fx.Option
• func Log(ctx context.Context, fbl ...*zap.Logger) *zap.Logger
• func LoggerFromContext(ctx context.Context) (*zap.Logger, bool)
• func Observed() fx.Option
• func Provide() fx.Option
• func TestProvide() fx.Option
• func TraceHook() func(ctx context.Context, f []zap.Field) []zap.Field
• func WithLogger(ctx context.Context, logs *zap.Logger) context.Context
• type Config
• type ContextHook
• type ContextLogger
  • func NewContextLogger(logs *zap.Logger, hook ...ContextHook) *ContextLogger
  • func NewTraceContextLogger(logs *zap.Logger) *ContextLogger
  • func (log *ContextLogger) Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry
  • func (log *ContextLogger) DPanic(ctx context.Context, msg string, fields ...zap.Field)
  • func (log *ContextLogger) Debug(ctx context.Context, msg string, fields ...zap.Field)
  • func (log *ContextLogger) Error(ctx context.Context, msg string, fields ...zap.Field)
  • func (log *ContextLogger) Fatal(ctx context.Context, msg string, fields ...zap.Field)
  • func (log *ContextLogger) Info(ctx context.Context, msg string, fields ...zap.Field)
  • func (log *ContextLogger) Level() zapcore.Level
  • func (log *ContextLogger) Log(ctx context.Context, lvl zapcore.Level, msg string, fields ...zap.Field)
  • func (log *ContextLogger) Named(s string) *ContextLogger
  • func (log *ContextLogger) Panic(ctx context.Context, msg string, fields ...zap.Field)
  • func (log *ContextLogger) Sync() error
  • func (log *ContextLogger) Warn(ctx context.Context, msg string, fields ...zap.Field)
  • func (log *ContextLogger) With(fields ...zap.Field) *ContextLogger
  • func (log *ContextLogger) WithOptions(opts ...zap.Option) *ContextLogger

Variables

var LambdaRequestIDKey = "requestId" //nolint:gochecknoglobals

LambdaRequestIDKey determines the logging key for the AWS request id from the lambda context.

Functions

func Fx

func Fx() fx.Option

Fx is a convenient option that configures fx to use the zap logger.

func Log

func Log(ctx context.Context, fbl ...*zap.Logger) *zap.Logger

Log retrieves a zap logger from the context. If the optional fallback logger is provided this logger is returned when the context has no logger, else a no-op logger is returned. If the context also has tracing and or span information this will be logged by the logger automatically.

func LoggerFromContext

func LoggerFromContext(ctx context.Context) (*zap.Logger, bool)

LoggerFromContext attempts to get a zap logger from the context. Returns nil and false if there is no logger in the context.

func Observed

func Observed() fx.Option

Observed configures a logging module that allows for observing while also writing console output to a io.Writer that needs to be supplied.

func Provide

func Provide() fx.Option

Provide logging module. It can be used as a fx Module in production binaries to provide high-performance structured logging.

func TestProvide

func TestProvide() fx.Option

TestProvide is a convenient fx option setup that can easily be included in all tests. It observed the logs for assertion and writes console output to the GinkgoWriter so all logs can easily be inspected if tests fail.

func TraceHook

func TraceHook() func(ctx context.Context, f []zap.Field) []zap.Field

TraceHook creates a context logger hook that appends trace information.

func WithLogger

func WithLogger(ctx context.Context, logs *zap.Logger) context.Context

WithLogger returns a context with the provided logger embedded.

Types

type Config

type Config struct {
	// Level configures the minium logging level that will be captured.
	Level zapcore.Level `env:"LEVEL" envDefault:"info"`
	// Outputs configures the zap outputs that will be opened for logging.
	Outputs []string `env:"OUTPUTS" envDefault:"stderr"`
	// Configure the level at which fx logs are shown, default to debug
	FxLevel zapcore.Level `env:"FX_LEVEL" envDefault:"debug"`
	// By default it logs to lambda format, this
	DisableLambdaEncoding bool `env:"DISABLE_LAMBDA_ENCODING"`
}

Config configures the logging package.

type ContextHook

type ContextHook func(ctx context.Context, f []zap.Field) []zap.Field

ContextHook allows adding fields based on the context.

type ContextLogger

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

ContextLogger wraps a zap loger but only allows logging with a context. This allows users to force the logging of contextual fields such as trace-ids that would otherwise cause logs to not be observable per trace. It is not provided as a dependency to fx because it is expected that this logger is initialized inside the components on a case-by-case basis. We want the signature of components constructs NOT to be dependant on a contextual logger, to imporove portability.

Deprecated: the less surprising way to do contextual logging is to embed the logger in the context. This approach can be found in the ctx.go. It is also simpler and doesn't require a home-made type. The ContextLogger was mainly useful to allow named loggers per component.

func NewContextLogger

func NewContextLogger(logs *zap.Logger, hook ...ContextHook) *ContextLogger

NewContextLogger inits our contextual with the underlying zapcore logger.

func NewTraceContextLogger

func NewTraceContextLogger(logs *zap.Logger) *ContextLogger

NewTraceContextLogger inits a contextual logger that adds trace information to each log line.

func (*ContextLogger) Check

func (log *ContextLogger) Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry

Check returns a CheckedEntry if logging a message at the specified level is enabled. It's a completely optional optimization; in high-performance applications, Check can help avoid allocating a slice to hold fields.

func (*ContextLogger) DPanic

func (log *ContextLogger) DPanic(ctx context.Context, msg string, fields ...zap.Field)

DPanic logs a message at DPanicLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

If the logger is in development mode, it then panics (DPanic means "development panic"). This is useful for catching errors that are recoverable, but shouldn't ever happen.

func (*ContextLogger) Debug

func (log *ContextLogger) Debug(ctx context.Context, msg string, fields ...zap.Field)

Debug logs a message at DebugLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (*ContextLogger) Error

func (log *ContextLogger) Error(ctx context.Context, msg string, fields ...zap.Field)

Error logs a message at ErrorLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (*ContextLogger) Fatal

func (log *ContextLogger) Fatal(ctx context.Context, msg string, fields ...zap.Field)

Fatal logs a message at FatalLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

The logger then calls os.Exit(1), even if logging at FatalLevel is disabled.

func (*ContextLogger) Info

func (log *ContextLogger) Info(ctx context.Context, msg string, fields ...zap.Field)

Info logs a message at InfoLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (*ContextLogger) Level

func (log *ContextLogger) Level() zapcore.Level

Level reports the minimum enabled level for this logger.

For NopLoggers, this is zapcore.InvalidLevel.

func (*ContextLogger) Log

func (log *ContextLogger) Log(ctx context.Context, lvl zapcore.Level, msg string, fields ...zap.Field)

Log logs a message at the specified level. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (*ContextLogger) Named

func (log *ContextLogger) Named(s string) *ContextLogger

Named adds a new path segment to the logger's name. Segments are joined by periods. By default, Loggers are unnamed.

func (*ContextLogger) Panic

func (log *ContextLogger) Panic(ctx context.Context, msg string, fields ...zap.Field)

Panic logs a message at PanicLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

The logger then panics, even if logging at PanicLevel is disabled.

func (*ContextLogger) Sync

func (log *ContextLogger) Sync() error

Sync calls the underlying Core's Sync method, flushing any buffered log entries. Applications should take care to call Sync before exiting.

func (*ContextLogger) Warn

func (log *ContextLogger) Warn(ctx context.Context, msg string, fields ...zap.Field)

Warn logs a message at WarnLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

func (*ContextLogger) With

func (log *ContextLogger) With(fields ...zap.Field) *ContextLogger

With creates a child logger and adds structured context to it. Fields added to the child don't affect the parent, and vice versa.

func (*ContextLogger) WithOptions

func (log *ContextLogger) WithOptions(opts ...zap.Option) *ContextLogger

WithOptions clones the current Logger, applies the supplied Options, and returns the resulting Logger. It's safe to use concurrently.