log

Documentation

Overview

Package log provides structured logging for Core applications.

The package works standalone or integrated with the Core framework:

// Standalone usage
log.SetLevel(log.LevelDebug)
log.Info("server started", "port", 8080)
log.Error("failed to connect", "err", err)

// With Core framework
core.New(
    framework.WithName("log", log.NewService(log.Options{Level: log.LevelInfo})),
)

Index

• func As(err error, target any) bool
• func Debug(msg string, keyvals ...any)
• func E(op, msg string, err error) error
• func ErrCode(err error) string
• func Error(msg string, keyvals ...any)
• func Info(msg string, keyvals ...any)
• func Is(err, target error) bool
• func Join(errs ...error) error
• func LogError(err error, op, msg string) error
• func LogWarn(err error, op, msg string) error
• func Message(err error) string
• func Must(err error, op, msg string)
• func NewCode(code, msg string) error
• func NewError(text string) error
• func NewService(opts Options) func(*framework.Core) (any, error)
• func Op(err error) string
• func Root(err error) error
• func SetDefault(l *Logger)
• func SetLevel(level Level)
• func Warn(msg string, keyvals ...any)
• func Wrap(err error, op, msg string) error
• func WrapCode(err error, code, op, msg string) error
• type Err
  • func (e *Err) Error() string
  • func (e *Err) Unwrap() error
• type Level
  • func (l Level) String() string
• type Logger
  • func Default() *Logger
  • func New(opts Options) *Logger
  • func (l *Logger) Debug(msg string, keyvals ...any)
  • func (l *Logger) Error(msg string, keyvals ...any)
  • func (l *Logger) Info(msg string, keyvals ...any)
  • func (l *Logger) Level() Level
  • func (l *Logger) SetLevel(level Level)
  • func (l *Logger) SetOutput(w io.Writer)
  • func (l *Logger) Warn(msg string, keyvals ...any)
• type Options
• type QueryLevel
• type Service
  • func (s *Service) OnStartup(ctx context.Context) error
• type TaskSetLevel

Functions

func As

func As(err error, target any) bool

As finds the first error in err's tree that matches target. Wrapper around errors.As for convenience.

func Debug

func Debug(msg string, keyvals ...any)

Debug logs to the default logger.

func E

func E(op, msg string, err error) error

E creates a new Err with operation context. The underlying error can be nil for creating errors without a cause.

Example:

return log.E("user.Save", "failed to save user", err)
return log.E("api.Call", "rate limited", nil)  // No underlying cause

func ErrCode

func ErrCode(err error) string

ErrCode extracts the error code from an error. Returns empty string if the error is not an *Err or has no code.

func Error

func Error(msg string, keyvals ...any)

Error logs to the default logger.

func Info

func Info(msg string, keyvals ...any)

Info logs to the default logger.

func Is

func Is(err, target error) bool

Is reports whether any error in err's tree matches target. Wrapper around errors.Is for convenience.

func Join

func Join(errs ...error) error

Join combines multiple errors into one. Wrapper around errors.Join for convenience.

func LogError

func LogError(err error, op, msg string) error

LogError logs an error at Error level and returns a wrapped error. Reduces boilerplate in error handling paths.

Example:

// Before
if err != nil {
    log.Error("failed to save", "err", err)
    return errors.Wrap(err, "user.Save", "failed to save")
}

// After
if err != nil {
    return log.LogError(err, "user.Save", "failed to save")
}

func LogWarn

func LogWarn(err error, op, msg string) error

LogWarn logs at Warn level and returns a wrapped error. Use for recoverable errors that should be logged but not treated as critical.

Example:

return log.LogWarn(err, "cache.Get", "cache miss, falling back to db")

func Message

func Message(err error) string

Message extracts the message from an error. Returns the error's Error() string if not an *Err.

func Must

func Must(err error, op, msg string)

Must panics if err is not nil, logging first. Use for errors that should never happen and indicate programmer error.

Example:

log.Must(Initialize(), "app", "startup failed")

func NewCode

func NewCode(code, msg string) error

NewCode creates an error with just code and message (no underlying error). Useful for creating sentinel errors with codes.

Example:

var ErrNotFound = log.NewCode("NOT_FOUND", "resource not found")

func NewError

func NewError(text string) error

NewError creates a simple error with the given text. Wrapper around errors.New for convenience.

func NewService

func NewService(opts Options) func(*framework.Core) (any, error)

NewService creates a log service factory for Core.

func Op

func Op(err error) string

Op extracts the operation name from an error. Returns empty string if the error is not an *Err.

func Root

func Root(err error) error

Root returns the root cause of an error chain. Unwraps until no more wrapped errors are found.

func SetDefault

func SetDefault(l *Logger)

SetDefault sets the default logger.

func SetLevel

func SetLevel(level Level)

SetLevel sets the default logger's level.

func Warn

func Warn(msg string, keyvals ...any)

Warn logs to the default logger.

func Wrap

func Wrap(err error, op, msg string) error

Wrap wraps an error with operation context. Returns nil if err is nil, to support conditional wrapping. Preserves error Code if the wrapped error is an *Err.

Example:

return log.Wrap(err, "db.Query", "database query failed")

func WrapCode

func WrapCode(err error, code, op, msg string) error

WrapCode wraps an error with operation context and error code. Returns nil only if both err is nil AND code is empty. Useful for API errors that need machine-readable codes.

Example:

return log.WrapCode(err, "VALIDATION_ERROR", "user.Validate", "invalid email")

Types

type Err

type Err struct {
	Op   string // Operation being performed (e.g., "user.Save")
	Msg  string // Human-readable message
	Err  error  // Underlying error (optional)
	Code string // Error code (optional, e.g., "VALIDATION_FAILED")
}

Err represents a structured error with operational context. It implements the error interface and supports unwrapping.

func (*Err) Error

func (e *Err) Error() string

Error implements the error interface.

func (*Err) Unwrap

func (e *Err) Unwrap() error

Unwrap returns the underlying error for use with errors.Is and errors.As.

type Level

type Level int

Level defines logging verbosity.

const (
	// LevelQuiet suppresses all log output.
	LevelQuiet Level = iota
	// LevelError shows only error messages.
	LevelError
	// LevelWarn shows warnings and errors.
	LevelWarn
	// LevelInfo shows informational messages, warnings, and errors.
	LevelInfo
	// LevelDebug shows all messages including debug details.
	LevelDebug
)

Logging level constants ordered by increasing verbosity.

func (Level) String

func (l Level) String() string

String returns the level name.

type Logger

type Logger struct {

	// Style functions for formatting (can be overridden)
	StyleTimestamp func(string) string
	StyleDebug     func(string) string
	StyleInfo      func(string) string
	StyleWarn      func(string) string
	StyleError     func(string) string
	// contains filtered or unexported fields
}

Logger provides structured logging.

func Default

func Default() *Logger

Default returns the default logger.

func New

func New(opts Options) *Logger

New creates a new Logger with the given options.

func (*Logger) Debug

func (l *Logger) Debug(msg string, keyvals ...any)

Debug logs a debug message with optional key-value pairs.

func (*Logger) Error

func (l *Logger) Error(msg string, keyvals ...any)

Error logs an error message with optional key-value pairs.

func (*Logger) Info

func (l *Logger) Info(msg string, keyvals ...any)

Info logs an info message with optional key-value pairs.

func (*Logger) Level

func (l *Logger) Level() Level

Level returns the current log level.

func (*Logger) SetLevel

func (l *Logger) SetLevel(level Level)

SetLevel changes the log level.

func (*Logger) SetOutput

func (l *Logger) SetOutput(w io.Writer)

SetOutput changes the output writer.

func (*Logger) Warn

func (l *Logger) Warn(msg string, keyvals ...any)

Warn logs a warning message with optional key-value pairs.

type Options

type Options struct {
	Level  Level
	Output io.Writer // defaults to os.Stderr
}

Options configures a Logger.

type QueryLevel

type QueryLevel struct{}

QueryLevel returns the current log level.

type Service

type Service struct {
	*framework.ServiceRuntime[Options]
	*Logger
}

Service wraps Logger for Core framework integration.

func (*Service) OnStartup

func (s *Service) OnStartup(ctx context.Context) error

OnStartup registers query and task handlers.

type TaskSetLevel

type TaskSetLevel struct {
	Level Level
}

TaskSetLevel changes the log level.