fxlogging

README

Logging Module

This module provides configuration for Ubers zap logger. Almost all other modules expect a *zap.Logger to be present, so this module is as close to mandatory as is possible.

All logging will be done on stdout. It is assumed that any further log management facilities are provided by the underlying platform. There is no support for logging to a file, rotation or shipping logs, etc.

All logs emitted by the fx system itself are also logged via the zap Logger. In development mode all events are logged at Debug level, errors are logged at Error level. In preproduction and production mode only Error events are logged.

Components

The module lazily provides the following components:

• A *zap.Logger
• An adaptor which makes fx use the provided logger
• GrpcServerInterceptors that log all incoming requests
• GrpcClientInterceptors that log all requests made with the client
• GrpcServerInterceptors that embed a *zap.Logger, enriched with request metadata, in the context
• GrpcClientInterceptors that set peer.service metadata, which are logged by the server
• HttpMiddleware that logs all incoming requests on the server

Options

• WithZapOption Allows passing in additional options that will be fed through to the zap.Logger constructor without modification.
• WithFxLoggerOption Allows you to further configure the logging of the fx system itself
• WithGrpcServerInterceptorOptions and WithGrpcClientInterceptorOptions Allows customization of the provided grpc interceptor loggers. See interceptor.Option
• WithGrpcClientInterceptors By default the module supplies client logging interceptors. In certain high volume cases this is not desirable. With this option they can be removed from the system.

fx.Supply(fx.Annotate(fxlogger.WithLogLevel(zapcore.InfoLevel), fx.ResultTags(`group:"fxlogger_opts"`)))

Configuration file

At the moment the configuration for the logger only has a single option: mode:

• development (default): Uses zap's Development preset. Logs at debug level in a pretty printed format
• production: Uses zap's Production preset. Ensures timestamps are in UTC.
• preproduction: Same as production, but lowers level to debug and disables sampling.

All loggers print to stdout instead of stderr.

The settings behind each mode may be tuned further to suit the logging needs in each environment.

Documentation

Overview

Package fxlogging provides a convenient way to create loggers.

Example

package main

import (
	"time"

	sconfig "github.com/exoscale/stelling/config"
	"github.com/exoscale/stelling/fxlogging"
	"github.com/exoscale/stelling/fxsentry"
	"go.uber.org/fx"
	"go.uber.org/zap"
)

type Config struct {
	fxlogging.Logging
	fxsentry.Sentry
	APIKey sconfig.Secret
}

func main() {
	conf := &Config{}
	args := []string{"logging-test", "--logging.mode", "production", "--api-key", "my-key"}
	if err := sconfig.Load(conf, args); err != nil {
		panic(err)
	}
	app := fx.New(fx.Options(
		fxlogging.NewModule(
			conf,
			// these options make the logs determistic so we can test the output
			// Normal programs will 90% of the time only need the standard module
			// It does however demonstrate how additional zap options can be injected
			fxlogging.WithZapOption(zap.WithCaller(false)),
			fxlogging.WithZapOption(zap.WithClock(&fixedClock{ts: 1257894000})),
		),
		fx.Invoke(run),
	))

	app.Run()

}

func run(sd fx.Shutdowner, logger *zap.Logger) {
	logger.Info("Example log")
	sd.Shutdown() //nolint:errcheck
}

type fixedClock struct {
	ts int64
}

func (c *fixedClock) Now() time.Time {
	return time.Unix(c.ts, 0).UTC()
}

func (c *fixedClock) NewTicker(d time.Duration) *time.Ticker {
	return time.NewTicker(d)
}

Output:
{"level":"info","ts":"2009-11-10T23:00:00.000Z","msg":"Using configuration","conf":{"Mode":"production","Dsn":"","Environment":"prod","Debug":false,"Process":"","APIKey":"*****"}}
{"level":"info","ts":"2009-11-10T23:00:00.000Z","msg":"Example log"}
{"level":"info","ts":"2009-11-10T23:00:00.000Z","msg":"Final configuration","conf":{"Mode":"production","Dsn":"","Environment":"prod","Debug":false,"Process":"","APIKey":"*****"}}

Index

• Constants
• func ISO8601UTCTimeEncoder(t time.Time, enc zapcore.PrimitiveArrayEncoder)
• func NewGrpcInjectLoggerInterceptors(logger *zap.Logger, opts ...interceptor.Option) (*fxgrpc.UnaryServerInterceptor, *fxgrpc.StreamServerInterceptor)
• func NewGrpcInjectPeerInterceptors() (*fxgrpc.UnaryClientInterceptor, *fxgrpc.StreamClientInterceptor)
• func NewGrpcLoggingClientInterceptors(logger *zap.Logger, opts ...interceptor.Option) (*fxgrpc.UnaryClientInterceptor, *fxgrpc.StreamClientInterceptor)
• func NewGrpcLoggingServerInterceptors(logger *zap.Logger, opts ...interceptor.Option) (*fxgrpc.UnaryServerInterceptor, *fxgrpc.StreamServerInterceptor)
• func NewLogger(conf LoggingConfig, lc fx.Lifecycle, opts ...zap.Option) (*zap.Logger, error)
• func NewModule(conf LoggingConfig, opts ...Option) fx.Option
• type HttpMiddlewareResult
  • func NewHttpMiddleware(logger *zap.Logger) HttpMiddlewareResult
• type Logging
  • func (l *Logging) LoggingConfig() *Logging
  • func (l *Logging) MarshalLogObject(enc zapcore.ObjectEncoder) error
• type LoggingConfig
• type Option
  • func WithFxLoggerOption(opt fxlogger.Option) Option
  • func WithGrpcClientInterceptorOptions(opt interceptor.Option) Option
  • func WithGrpcClientInterceptors(enabled bool) Option
  • func WithGrpcServerInterceptorOptions(opt interceptor.Option) Option
  • func WithZapOption(opt zap.Option) Option

Examples

• Package

Constants

const GrpcInterceptorWeight uint = 50

Functions

func ISO8601UTCTimeEncoder

func ISO8601UTCTimeEncoder(t time.Time, enc zapcore.PrimitiveArrayEncoder)

ISO8601UTCTimeEncoder is like zapcore.ISO8601TimeEncoder but sets the timezone to utc first

func NewGrpcInjectLoggerInterceptors

func NewGrpcInjectLoggerInterceptors(logger *zap.Logger, opts ...interceptor.Option) (*fxgrpc.UnaryServerInterceptor, *fxgrpc.StreamServerInterceptor)

func NewGrpcInjectPeerInterceptors

func NewGrpcInjectPeerInterceptors() (*fxgrpc.UnaryClientInterceptor, *fxgrpc.StreamClientInterceptor)

func NewGrpcLoggingClientInterceptors

func NewGrpcLoggingClientInterceptors(logger *zap.Logger, opts ...interceptor.Option) (*fxgrpc.UnaryClientInterceptor, *fxgrpc.StreamClientInterceptor)

func NewGrpcLoggingServerInterceptors

func NewGrpcLoggingServerInterceptors(logger *zap.Logger, opts ...interceptor.Option) (*fxgrpc.UnaryServerInterceptor, *fxgrpc.StreamServerInterceptor)

func NewLogger

func NewLogger(conf LoggingConfig, lc fx.Lifecycle, opts ...zap.Option) (*zap.Logger, error)

func NewModule

func NewModule(conf LoggingConfig, opts ...Option) fx.Option

NewModule provides a *zap.Logger to the system It also provides the following related items: * Grpc middleware * An adapter to log fx system events

Types

type HttpMiddlewareResult

type HttpMiddlewareResult struct {
	fx.Out

	Middleware *fxhttp.Middleware `group:"http_middleware"`
}

func NewHttpMiddleware

func NewHttpMiddleware(logger *zap.Logger) HttpMiddlewareResult

type Logging

type Logging struct {
	// LogMode is the preset logging configuration
	Mode string `default:"development" validate:"oneof=production development preproduction"`
}

Logging contains the configuration options for the logging module

func (*Logging) LoggingConfig

func (l *Logging) LoggingConfig() *Logging

func (*Logging) MarshalLogObject

func (l *Logging) MarshalLogObject(enc zapcore.ObjectEncoder) error

type LoggingConfig

type LoggingConfig interface {
	LoggingConfig() *Logging
}

type Option

type Option func(*moduleConfig)

func WithFxLoggerOption

func WithFxLoggerOption(opt fxlogger.Option) Option

WithFxLoggerOption will apply the fxlogger Option to the logger used by the fx machinery Can be given multiple times to supply different options

func WithGrpcClientInterceptorOptions

func WithGrpcClientInterceptorOptions(opt interceptor.Option) Option

func WithGrpcClientInterceptors

func WithGrpcClientInterceptors(enabled bool) Option

WithGrpcClientInterceptors determines if Grpc Client interceptors can be provided by the system This is true by default, but is undesirable in high volume use cases If you app does not use gRPC you can ignore this: fx provides constructors lazily

func WithGrpcServerInterceptorOptions

func WithGrpcServerInterceptorOptions(opt interceptor.Option) Option

func WithZapOption

func WithZapOption(opt zap.Option) Option

WithZapOption will apply the given zap.Option to the logger provided by the module Can be given multiple times to supply different options