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 FormatStackTrace(err error) string
- 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 Security(msg string, keyvals ...any)
- func SetDefault(l *Logger)
- func SetLevel(level Level)
- func StackTrace(err error) []string
- func Username() string
- 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
- type Level
- type 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) Security(msg string, keyvals ...any)
- 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 RotatingWriter
- type RotationOptions
- type Service
- type TaskSetLevel
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As ¶
As finds the first error in err's tree that matches target. Wrapper around errors.As for convenience.
func E ¶
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 ¶
ErrCode extracts the error code from an error. Returns empty string if the error is not an *Err or has no code.
func FormatStackTrace ¶
FormatStackTrace returns a pretty-printed logical stack trace.
func Is ¶
Is reports whether any error in err's tree matches target. Wrapper around errors.Is for convenience.
func LogError ¶
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 ¶
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 ¶
Message extracts the message from an error. Returns the error's Error() string if not an *Err.
func Must ¶
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 ¶
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 ¶
NewError creates a simple error with the given text. Wrapper around errors.New for convenience.
func NewService ¶
NewService creates a log service factory for Core.
func Op ¶
Op extracts the operation name from an error. Returns empty string if the error is not an *Err.
func Root ¶
Root returns the root cause of an error chain. Unwraps until no more wrapped errors are found.
func StackTrace ¶
StackTrace returns the logical stack trace (chain of operations) from an error. It returns an empty slice if no operational context is found.
func Username ¶
func Username() string
Username returns the current system username. It uses os/user for reliability and falls back to environment variables.
func Wrap ¶
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")
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.
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.
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
StyleSecurity func(string) string
// contains filtered or unexported fields
}
Logger provides structured logging.
func (*Logger) Security ¶
Security logs a security event with optional key-value pairs. It uses LevelError to ensure security events are visible even in restrictive log configurations.
type Options ¶
type Options struct {
Level Level
// Output is the destination for log messages. If Rotation is provided,
// Output is ignored and logs are written to the rotating file instead.
Output io.Writer
// Rotation enables log rotation to file. If provided, Filename must be set.
Rotation *RotationOptions
}
Options configures a Logger.
type RotatingWriter ¶
type RotatingWriter struct {
// contains filtered or unexported fields
}
RotatingWriter implements io.WriteCloser and provides log rotation.
func NewRotatingWriter ¶
func NewRotatingWriter(opts RotationOptions, m coreio.Medium) *RotatingWriter
NewRotatingWriter creates a new RotatingWriter with the given options and medium.
func (*RotatingWriter) Close ¶
func (w *RotatingWriter) Close() error
Close closes the current log file.
type RotationOptions ¶
type RotationOptions struct {
// Filename is the log file path. If empty, rotation is disabled.
Filename string
// MaxSize is the maximum size of the log file in megabytes before it gets rotated.
// It defaults to 100 megabytes.
MaxSize int
// MaxAge is the maximum number of days to retain old log files based on their
// file modification time. It defaults to 28 days.
// Note: set to a negative value to disable age-based retention.
MaxAge int
// MaxBackups is the maximum number of old log files to retain.
// It defaults to 5 backups.
MaxBackups int
// Compress determines if the rotated log files should be compressed using gzip.
// It defaults to true.
Compress bool
}
RotationOptions defines the log rotation and retention policy.
Source Files