logger

Documentation

Index

• func Critical(l Logger, args ...interface{})
• func Criticalf(l Logger, format string, values ...interface{})
• func Criticalw(l Logger, msg string, keysAndValues ...interface{})
• func NewOCRWrapper(l Logger, trace bool, saveError func(string)) ocrtypes.Logger
• func Trace(l Logger, args ...interface{})
• func Tracef(l Logger, format string, values ...interface{})
• func Tracew(l Logger, msg string, keysAndValues ...interface{})
• type Config
  • func (c *Config) New() (Logger, error)
• type Logger
  • func Helper(l Logger, skip int) Logger
  • func Named(l Logger, n string) Logger
  • func New() (Logger, error)
  • func NewWith(cfgFn func(*zap.Config)) (Logger, error)
  • func NewWithSync(w io.Writer) Logger
  • func Nop() Logger
  • func Test(tb testing.TB) Logger
  • func TestObserved(tb testing.TB, lvl zapcore.Level) (Logger, *observer.ObservedLogs)
  • func With(l Logger, keyvals ...interface{}) Logger
• type SugaredLogger
  • func Sugared(l Logger) SugaredLogger
  • func TestObservedSugared(tb testing.TB, lvl zapcore.Level) (SugaredLogger, *observer.ObservedLogs)
  • func TestSugared(tb testing.TB) SugaredLogger

Functions

func Critical

func Critical(l Logger, args ...interface{})

Deprecated: instead use [SugaredLogger.Critical]:

Sugared(l).Critical(args...)

func Criticalf

func Criticalf(l Logger, format string, values ...interface{})

Deprecated: instead use [SugaredLogger.Criticalf]:

Sugared(l).Criticalf(args...)

func Criticalw

func Criticalw(l Logger, msg string, keysAndValues ...interface{})

Deprecated: instead use [SugaredLogger.Criticalw]:

Sugared(l).Criticalw(args...)

func NewOCRWrapper

func NewOCRWrapper(l Logger, trace bool, saveError func(string)) ocrtypes.Logger

NewOCRWrapper returns a new ocrtypes.Logger backed by the given Logger. Note: trace logs are written at debug level, regardless of any build tags.

func Trace

func Trace(l Logger, args ...interface{})

Deprecated: instead use [SugaredLogger.Trace]:

Sugared(l).Trace(args...)

func Tracef

func Tracef(l Logger, format string, values ...interface{})

Deprecated: instead use [SugaredLogger.Tracef]:

Sugared(l).Tracef(args...)

func Tracew

func Tracew(l Logger, msg string, keysAndValues ...interface{})

Deprecated: instead use [SugaredLogger.Tracew]:

Sugared(l).Tracew(args...)

Types

type Config

type Config struct {
	Level zapcore.Level
}

func (*Config) New

func (c *Config) New() (Logger, error)

New returns a new Logger for Config.

type Logger

type Logger interface {
	// Name returns the fully qualified name of the logger.
	Name() string

	Debug(args ...interface{})
	Info(args ...interface{})
	Warn(args ...interface{})
	Error(args ...interface{})
	Panic(args ...interface{})
	// Fatal logs and then calls os.Exit(1)
	// Be careful about using this since it does NOT unwind the stack and may exit uncleanly
	Fatal(args ...interface{})

	Debugf(format string, values ...interface{})
	Infof(format string, values ...interface{})
	Warnf(format string, values ...interface{})
	Errorf(format string, values ...interface{})
	Panicf(format string, values ...interface{})
	Fatalf(format string, values ...interface{})

	Debugw(msg string, keysAndValues ...interface{})
	Infow(msg string, keysAndValues ...interface{})
	Warnw(msg string, keysAndValues ...interface{})
	Errorw(msg string, keysAndValues ...interface{})
	Panicw(msg string, keysAndValues ...interface{})
	Fatalw(msg string, keysAndValues ...interface{})

	// Sync flushes any buffered log entries.
	// Some insignificant errors are suppressed.
	Sync() error
}

Logger is a basic logging interface implemented by smartcontractkit/chainlink/core/logger.Logger and go.uber.org/zap.SugaredLogger

Loggers should be injected (and usually Named as well): e.g. lggr.Named("<service name>")

Tests

• Tests should use a Test logger, with New being reserved for actual runtime and limited direct testing.

Levels

• Fatal: Logs and then calls os.Exit(1). Be careful about using this since it does NOT unwind the stack and may exit uncleanly.
• Panic: Unrecoverable error. Example: invariant violation, programmer error
• Error: Something bad happened, and it was clearly on the node op side. No need for immediate action though. Example: database write timed out
• Warn: Something bad happened, not clear who/what is at fault. Node ops should have a rough look at these once in a while to see whether anything stands out. Example: connection to peer was closed unexpectedly. observation timed out.
• Info: High level information. First level we’d expect node ops to look at. Example: entered new epoch with leader, made an observation with value, etc.
• Debug: Useful for forensic debugging, but we don't expect nops to look at this. Example: Got a message, dropped a message, ...

Node Operator Docs: https://docs.chain.link/docs/configuration-variables/#log_level

func Helper

func Helper(l Logger, skip int) Logger

Helper returns a logger with 'skip' levels of callers skipped, if 'l' has a method `Helper(int) L`, where L implements Logger, otherwise it returns l. See zap.AddCallerSkip

func Named

func Named(l Logger, n string) Logger

Named returns a logger with name 'n', if 'l' has a method `Named(string) L`, where L implements Logger, otherwise it returns l.

func New

func New() (Logger, error)

New returns a new Logger with the default configuration.

func NewWith

func NewWith(cfgFn func(*zap.Config)) (Logger, error)

NewWith returns a new Logger from a modified zap.Config.

func NewWithSync

func NewWithSync(w io.Writer) Logger

NewWithSync returns a new Logger with a given SyncWriter.

func Nop

func Nop() Logger

Nop returns a no-op Logger.

func Test

func Test(tb testing.TB) Logger

Test returns a new test Logger for tb.

func TestObserved

func TestObserved(tb testing.TB, lvl zapcore.Level) (Logger, *observer.ObservedLogs)

TestObserved returns a new test Logger for tb and ObservedLogs at the given Level.

func With

func With(l Logger, keyvals ...interface{}) Logger

With returns a Logger with keyvals, if 'l' has a method `With(...interface{}) L`, where L implements Logger, otherwise it returns l.

type SugaredLogger

type SugaredLogger interface {
	Logger

	// AssumptionViolation variants log at error level with the message prefix "AssumptionViolation: ".
	AssumptionViolation(args ...interface{})
	AssumptionViolationf(format string, vals ...interface{})
	AssumptionViolationw(msg string, keysAndVals ...interface{})

	// ErrorIf logs the error if present.
	ErrorIf(err error, msg string)
	// ErrorIfFn calls fn() and logs any returned error along with msg.
	// Unlike ErrorIf, this can be deffered inline, since the function call is delayed:
	//
	//	defer lggr.ErrorIfFn(resource.Close, "Failed to close resource")
	ErrorIfFn(fn func() error, msg string)

	// Critical emits critical level logs (a remapping of [zap.DPanicLevel]) or falls back to error level with a '[crit]' prefix.
	Critical(args ...interface{})
	Criticalf(format string, vals ...interface{})
	Criticalw(msg string, keysAndVals ...interface{})

	// Trace emits logs only when built with the 'trace' tag.
	//
	//	go test -tags trace ./foo -run TestBar
	Trace(args ...interface{})
	Tracef(format string, vals ...interface{})
	Tracew(msg string, keysAndVals ...interface{})

	// Named creates a new Logger sub-scoped with name.
	// Names are inherited and dot-separated.
	//   a := l.Named("A") // logger=A
	//   b := a.Named("A") // logger=A.B
	// Names are generally `MixedCaps`, without spaces, like Go names. `Foo.Bar.HTTPBaz`
	Named(string) SugaredLogger
	// With returns a new Logger with the given arguments.
	With(keyvals ...any) SugaredLogger
	// Helper returns a new logger with the number of callers skipped by caller annotation increased by skip.
	// This allows wrappers and helpers to point higher up the stack (like testing.T.Helper()).
	Helper(skip int) SugaredLogger
}

SugaredLogger extends the base Logger interface with syntactic sugar, similar to zap.SugaredLogger, include two new levels.

• Critical: Requires quick action from the node op, obviously these should happen extremely rarely. Example: failed to listen on TCP port
• Trace: Only included if compiled with the trace tag. For example: go test -tags trace ...

func Sugared

func Sugared(l Logger) SugaredLogger

Sugared returns a new SugaredLogger wrapping the given Logger. Prefer to store the SugaredLogger for reuse, instead of recreating it as needed.

func TestObservedSugared

func TestObservedSugared(tb testing.TB, lvl zapcore.Level) (SugaredLogger, *observer.ObservedLogs)

TestObservedSugared returns a new test SugaredLogger for tb and ObservedLogs at the given Level.

func TestSugared

func TestSugared(tb testing.TB) SugaredLogger

TestSugared returns a new test SugaredLogger.