log

README

Log

The cosmossdk.io/log provides a zerolog logging implementation for the Cosmos SDK and Cosmos SDK modules.

To use a logger wrapping an instance of the standard library's log/slog package, use cosmossdk.io/log/slog.

Documentation

Index

• Constants
• Variables
• func NewFilterWriter(parent io.Writer, filter FilterFunc) io.Writer
• func WithJSONMarshal(marshaler func(v any) ([]byte, error))
• type Config
• type FilterFunc
  • func ParseLogLevel(levelStr string) (FilterFunc, error)
• type Logger
  • func NewCustomLogger(logger zerolog.Logger) Logger
  • func NewLogger(dst io.Writer, options ...Option) Logger
  • func NewNopLogger() Logger
  • func NewTestLogger(t TestingT) Logger
  • func NewTestLoggerError(t TestingT) Logger
  • func NewTestLoggerInfo(t TestingT) Logger
• type Option
  • func ColorOption(val bool) Option
  • func FilterOption(filter FilterFunc) Option
  • func HooksOption(hooks ...zerolog.Hook) Option
  • func LevelOption(level zerolog.Level) Option
  • func OutputJSONOption() Option
  • func TimeFormatOption(format string) Option
  • func TraceOption(val bool) Option
  • func VerboseLevelOption(level zerolog.Level) Option
• type TestingT
• type VerboseModeLogger

Constants

const ModuleKey = "module"

ModuleKey defines a module logging key.

Variables

var ContextKey contextKey

ContextKey is used to store the logger in the context.

Functions

func NewFilterWriter

func NewFilterWriter(parent io.Writer, filter FilterFunc) io.Writer

NewFilterWriter returns a writer that filters out all key/value pairs that do not match the filter. If the filter is nil, the writer will pass all events through. The filter function is called with the module and level of the event.

func WithJSONMarshal

func WithJSONMarshal(marshaler func(v any) ([]byte, error))

WithJSONMarshal configures zerolog global json encoding.

Types

type Config

type Config struct {
	// Level is the default logging level.
	Level zerolog.Level
	// VerboseLevel is the logging level to use when verbose mode is enabled.
	// If there is a filter enabled, it will be disabled when verbose mode is enabled
	// and all log messages will be emitted at the VerboseLevel.
	// If this is set to NoLevel, then no changes to the logging level or filter will be made
	// when verbose mode is enabled.
	VerboseLevel zerolog.Level
	// Filter is the filter function to use that allows for filtering by key and level.
	// When verbose mode is enabled, the filter will be disabled unless VerboseLevel is set to NoLevel.
	Filter     FilterFunc
	OutputJSON bool
	Color      bool
	StackTrace bool
	TimeFormat string
	Hooks      []zerolog.Hook
}

Config defines configuration for the logger.

type FilterFunc

type FilterFunc func(key, level string) bool

FilterFunc is a function that returns true if the log level is filtered for the given key When the filter returns true, the log entry is discarded.

func ParseLogLevel

func ParseLogLevel(levelStr string) (FilterFunc, error)

ParseLogLevel parses complex log level A comma-separated list of module:level pairs with an optional *:level pair (* means all other modules).

Example: ParseLogLevel("consensus:debug,mempool:debug,*:error")

This function attempts to keep the same behavior as the CometBFT ParseLogLevel However the level `none` is replaced by `disabled`.

type Logger

type Logger interface {
	// Info takes a message and a set of key/value pairs and logs with level INFO.
	// The key of the tuple must be a string.
	Info(msg string, keyVals ...any)

	// Warn takes a message and a set of key/value pairs and logs with level WARN.
	// The key of the tuple must be a string.
	Warn(msg string, keyVals ...any)

	// Error takes a message and a set of key/value pairs and logs with level ERR.
	// The key of the tuple must be a string.
	Error(msg string, keyVals ...any)

	// Debug takes a message and a set of key/value pairs and logs with level DEBUG.
	// The key of the tuple must be a string.
	Debug(msg string, keyVals ...any)

	// With returns a new wrapped logger with additional context provided by a set.
	With(keyVals ...any) Logger

	// Impl returns the underlying logger implementation.
	// It is used to access the full functionalities of the underlying logger.
	// Advanced users can type cast the returned value to the actual logger.
	Impl() any
}

Logger is the Cosmos SDK logger interface.

func NewCustomLogger

func NewCustomLogger(logger zerolog.Logger) Logger

NewCustomLogger returns a new logger with the given zerolog logger.

func NewLogger

func NewLogger(dst io.Writer, options ...Option) Logger

NewLogger returns a new logger that writes to the given destination.

Typical usage from a main function is:

logger := log.NewLogger(os.Stderr)

Stderr is the typical destination for logs, so that any output from your application can still be piped to other processes.

func NewNopLogger

func NewNopLogger() Logger

NewNopLogger returns a new logger that does nothing.

func NewTestLogger

func NewTestLogger(t TestingT) Logger

NewTestLogger returns a logger that calls t.Log to write entries.

The returned logger emits messages at any level. For active debugging of a test with verbose logs, the NewTestLoggerInfo and NewTestLoggerError functions only emit messages at or above the corresponding log levels.

If the logs may help debug a test failure, you may want to use NewTestLogger(t) in your test. Otherwise, use NewNopLogger().

func NewTestLoggerError

func NewTestLoggerError(t TestingT) Logger

NewTestLoggerError returns a test logger that filters out messages below Error level.

This is primarily helpful during active debugging of a test with verbose logs.

func NewTestLoggerInfo

func NewTestLoggerInfo(t TestingT) Logger

NewTestLoggerInfo returns a test logger that filters out messages below info level.

This is primarily helpful during active debugging of a test with verbose logs.

type Option

type Option func(*Config)

func ColorOption

func ColorOption(val bool) Option

ColorOption add option to enable/disable coloring of the logs when console writer is in use

func FilterOption

func FilterOption(filter FilterFunc) Option

FilterOption sets the filter for the Logger.

func HooksOption

func HooksOption(hooks ...zerolog.Hook) Option

HooksOption append hooks to the Logger hooks

func LevelOption

func LevelOption(level zerolog.Level) Option

LevelOption sets the level for the Logger. Messages with a lower level will be discarded.

func OutputJSONOption

func OutputJSONOption() Option

OutputJSONOption sets the output of the logger to JSON. By default, the logger outputs to a human-readable format.

func TimeFormatOption

func TimeFormatOption(format string) Option

TimeFormatOption configures timestamp format of the logger timestamps disabled if empty. it is responsibility of the caller to provider correct values Supported formats:

• time.Layout
• time.ANSIC
• time.UnixDate
• time.RubyDate
• time.RFC822
• time.RFC822Z
• time.RFC850
• time.RFC1123
• time.RFC1123Z
• time.RFC3339
• time.RFC3339Nano
• time.Kitchen

func TraceOption

func TraceOption(val bool) Option

TraceOption add option to enable/disable print of stacktrace on error log

func VerboseLevelOption

func VerboseLevelOption(level zerolog.Level) Option

VerboseLevelOption sets the verbose level for the Logger. When verbose mode is enabled, the logger will be switched to this level.

type TestingT

type TestingT zerolog.TestingLog

TestingT is the interface required for logging in tests. It is a subset of testing.T to avoid a direct dependency on the testing package.

type VerboseModeLogger

type VerboseModeLogger interface {
	Logger
	// SetVerboseMode configures whether the logger enters verbose mode or not for
	// special operations where increased observability of log messages is desired
	// (such as chain upgrades).
	SetVerboseMode(bool)
}

VerboseModeLogger is an extension interface of Logger which allows verbosity to be configured.