fxevent

Documentation

Overview

Package fxevent defines a means of changing how Fx logs internal events.

Changing the Logger

By default, the ConsoleLogger is used, writing readable logs to stderr.

You can use the fx.WithLogger option to change this behavior by providing a constructor that returns an alternative implementation of the Logger interface.

fx.WithLogger(func(cfg *Config) Logger {
	return &MyFxLogger{...}
})

Because WithLogger accepts a constructor, you can pull any other types and values from inside the container, allowing use of the same logger that your application uses.

For example, if you're using Zap inside your application, you can use the ZapLogger implementation of the interface.

fx.New(
	fx.Provide(
		zap.NewProduction, // provide a *zap.Logger
	),
	fx.WithLogger(
		func(log *zap.Logger) fxevent.Logger {
			return &fxevent.ZapLogger{Logger: log}
		},
	),
)

Implementing a Custom Logger

To implement a custom logger, you need to implement the Logger interface. The Logger.LogEvent method accepts an Event object.

Event is a union type that represents all the different events that Fx can emit. You can use a type switch to handle each event type. See 'event.go' for a list of all the possible events.

func (l *MyFxLogger) LogEvent(e fxevent.Event) {
	switch e := e.(type) {
	case *fxevent.OnStartExecuting:
		// ...
	// ...
	}
}

The events contain enough information for observability and debugging purposes. If you need more information in them, feel free to open an issue to discuss the addition.

Index

• Variables
• type ConsoleLogger
  • func (l *ConsoleLogger) LogEvent(event Event)
• type Decorated
• type Event
• type Invoked
• type Invoking
• type Logger
• type LoggerInitialized
• type OnStartExecuted
• type OnStartExecuting
• type OnStopExecuted
• type OnStopExecuting
• type Provided
• type Replaced
• type RolledBack
• type RollingBack
• type Run
• type SlogLogger
  • func (l *SlogLogger) LogEvent(event Event)
  • func (l *SlogLogger) UseContext(ctx context.Context)
  • func (l *SlogLogger) UseErrorLevel(level slog.Level)
  • func (l *SlogLogger) UseLogLevel(level slog.Level)
• type Started
• type Stopped
• type Stopping
• type Supplied
• type ZapLogger
  • func (l *ZapLogger) LogEvent(event Event)
  • func (l *ZapLogger) UseErrorLevel(level zapcore.Level)
  • func (l *ZapLogger) UseLogLevel(level zapcore.Level)

Variables

var NopLogger = nopLogger{}

NopLogger is an Fx event logger that ignores all messages.

Types

type ConsoleLogger

type ConsoleLogger struct {
	W io.Writer
}

ConsoleLogger is an Fx event logger that attempts to write human-readable messages to the console.

Use this during development.

func (*ConsoleLogger) LogEvent

func (l *ConsoleLogger) LogEvent(event Event)

LogEvent logs the given event to the provided Zap logger.

type Decorated

type Decorated struct {
	// DecoratorName is the name of the decorator function that was
	// provided to Fx.
	DecoratorName string

	// StackTrace is the stack trace of where the decorator was given to Fx.
	StackTrace []string

	// ModuleTrace contains the module locations through which this value was added.
	ModuleTrace []string

	// ModuleName is the name of the module in which the value was added to.
	ModuleName string

	// OutputTypeNames is a list of names of types that are decorated by
	// this decorator.
	OutputTypeNames []string

	// Err is non-nil if we failed to run this decorator.
	Err error
}

Decorated is emitted when a decorator is executed in Fx.

type Event

type Event interface {
	// contains filtered or unexported methods
}

Event defines an event emitted by fx.

type Invoked

type Invoked struct {
	// Functionname is the name of the function that was invoked.
	FunctionName string

	// ModuleName is the name of the module in which the value was added to.
	ModuleName string

	// Err is non-nil if the function failed to execute.
	Err error

	// Trace records information about where the fx.Invoke call was made.
	// Note that this is NOT a stack trace of the error itself.
	Trace string
}

Invoked is emitted after we invoke a function specified with fx.Invoke, whether it succeeded or failed.

type Invoking

type Invoking struct {
	// FunctionName is the name of the function that will be invoked.
	FunctionName string

	// ModuleName is the name of the module in which the value was added to.
	ModuleName string
}

Invoking is emitted before we invoke a function specified with fx.Invoke.

type Logger

type Logger interface {
	// LogEvent is called when a logging event is emitted.
	LogEvent(Event)
}

Logger defines interface used for logging.

type LoggerInitialized

type LoggerInitialized struct {
	// ConstructorName is the name of the constructor that builds this
	// logger.
	ConstructorName string

	// Err is non-nil if the logger failed to build.
	Err error
}

LoggerInitialized is emitted when a logger supplied with fx.WithLogger is instantiated, or if it fails to instantiate.

type OnStartExecuted

type OnStartExecuted struct {
	// FunctionName is the name of the function that was executed.
	FunctionName string

	// CallerName is the name of the function that scheduled the hook for
	// execution.
	CallerName string

	// Method specifies the kind of the hook. This is one of "OnStart" and
	// "OnStop".
	Method string

	// Runtime specifies how long it took to run this hook.
	Runtime time.Duration

	// Err is non-nil if the hook failed to execute.
	Err error
}

OnStartExecuted is emitted after an OnStart hook has been executed.

type OnStartExecuting

type OnStartExecuting struct {
	// FunctionName is the name of the function that will be executed.
	FunctionName string

	// CallerName is the name of the function that scheduled the hook for
	// execution.
	CallerName string
}

OnStartExecuting is emitted before an OnStart hook is executed.

type OnStopExecuted

type OnStopExecuted struct {
	// FunctionName is the name of the function that was executed.
	FunctionName string

	// CallerName is the name of the function that scheduled the hook for
	// execution.
	CallerName string

	// Runtime specifies how long it took to run this hook.
	Runtime time.Duration

	// Err is non-nil if the hook failed to execute.
	Err error
}

OnStopExecuted is emitted after an OnStop hook has been executed.

type OnStopExecuting

type OnStopExecuting struct {
	// FunctionName is the name of the function that will be executed.
	FunctionName string

	// CallerName is the name of the function that scheduled the hook for
	// execution.
	CallerName string
}

OnStopExecuting is emitted before an OnStop hook is executed.

type Provided

type Provided struct {
	// ConstructorName is the name of the constructor that was provided to
	// Fx.
	ConstructorName string

	// StackTrace is the stack trace of where the constructor was provided to Fx.
	StackTrace []string

	// ModuleTrace contains the module locations through which this was provided to Fx.
	ModuleTrace []string

	// OutputTypeNames is a list of names of types that are produced by
	// this constructor.
	OutputTypeNames []string

	// ModuleName is the name of the module in which the constructor was
	// provided to.
	ModuleName string

	// Err is non-nil if we failed to provide this constructor.
	Err error

	// Private denotes whether the provided constructor is a [Private] constructor.
	Private bool
}

Provided is emitted when a constructor is provided to Fx.

type Replaced

type Replaced struct {
	// OutputTypeNames is a list of names of types that were replaced.
	OutputTypeNames []string

	// StackTrace is the stack trace of the call to Replace.
	StackTrace []string

	// ModuleTrace contains the module locations through which this value was added.
	ModuleTrace []string

	// ModuleName is the name of the module in which the value was added to.
	ModuleName string

	// Err is non-nil if we failed to supply the value.
	Err error
}

Replaced is emitted when a value replaces a type in Fx.

type RolledBack

type RolledBack struct {
	// Err is non-nil if the rollback failed.
	Err error
}

RolledBack is emitted after a service has been rolled back, whether it succeeded or not.

type RollingBack

type RollingBack struct {
	// StartErr is the error that caused this rollback.
	StartErr error
}

RollingBack is emitted when the application failed to start up due to an error, and is being rolled back.

type Run

type Run struct {
	// Name is the name of the function that was run.
	Name string

	// Kind indicates which Fx option was used to pass along the function.
	// It is either "provide", "decorate", "supply", or "replace".
	Kind string

	// ModuleName is the name of the module in which the function belongs.
	ModuleName string

	// Runtime specifies how long it took to run this function.
	Runtime time.Duration

	// Err is non-nil if the function returned an error.
	// If fx.RecoverFromPanics is used, this will include panics.
	Err error
}

Run is emitted after a constructor, decorator, or supply/replace stub is run by Fx.

type SlogLogger

type SlogLogger struct {
	Logger *slog.Logger
	// contains filtered or unexported fields
}

SlogLogger an Fx event logger that logs events using a slog logger.

func (*SlogLogger) LogEvent

func (l *SlogLogger) LogEvent(event Event)

LogEvent logs the given event to the provided Zap logger.

func (*SlogLogger) UseContext

func (l *SlogLogger) UseContext(ctx context.Context)

UseContext sets the context that will be used when logging to slog.

func (*SlogLogger) UseErrorLevel

func (l *SlogLogger) UseErrorLevel(level slog.Level)

UseErrorLevel sets the level of error logs emitted by Fx to level.

func (*SlogLogger) UseLogLevel

func (l *SlogLogger) UseLogLevel(level slog.Level)

UseLogLevel sets the level of non-error logs emitted by Fx to level.

type Started

type Started struct {
	// Err is non-nil if the application failed to start successfully.
	Err error
}

Started is emitted when an application is started successfully and/or it errored.

type Stopped

type Stopped struct {
	// Err is non-nil if errors were encountered during shutdown.
	Err error
}

Stopped is emitted when the application has finished shutting down, whether successfully or not.

type Stopping

type Stopping struct {
	// Signal is the signal that caused this shutdown.
	Signal os.Signal
}

Stopping is emitted when the application receives a signal to shut down after starting. This may happen with fx.Shutdowner or by sending a signal to the application on the command line.

type Supplied

type Supplied struct {
	// TypeName is the name of the type of value that was added.
	TypeName string

	// StackTrace is the stack trace of the call to Supply.
	StackTrace []string

	// ModuleTrace contains the module locations through which this value was added.
	ModuleTrace []string

	// ModuleName is the name of the module in which the value was added to.
	ModuleName string

	// Err is non-nil if we failed to supply the value.
	Err error
}

Supplied is emitted after a value is added with fx.Supply.

type ZapLogger

type ZapLogger struct {
	Logger *zap.Logger
	// contains filtered or unexported fields
}

ZapLogger is an Fx event logger that logs events to Zap.

func (*ZapLogger) LogEvent

func (l *ZapLogger) LogEvent(event Event)

LogEvent logs the given event to the provided Zap logger.

func (*ZapLogger) UseErrorLevel

func (l *ZapLogger) UseErrorLevel(level zapcore.Level)

UseErrorLevel sets the level of error logs emitted by Fx to level.

func (*ZapLogger) UseLogLevel

func (l *ZapLogger) UseLogLevel(level zapcore.Level)

UseLogLevel sets the level of non-error logs emitted by Fx to level.