go-log/docs/api-contract.md

title	description
API Contract	Exported API surface for dappco.re/go/core/log

API Contract

This page enumerates the exported API surface of dappco.re/go/core/log.

Test coverage means there is an explicit test in log_test.go or errors_test.go that directly exercises the item. Indirect coverage through a different exported API is marked no.

Types

Name	Signature	Package Path	Description	Test Coverage
Err	type Err struct { Op string; Msg string; Err error; Code string }	dappco.re/go/core/log	Structured error with operation context, message, wrapped cause, and optional machine-readable code.	yes
Level	type Level int	dappco.re/go/core/log	Logging verbosity enum ordered from quiet to debug.	yes
Logger	type Logger struct { StyleTimestamp func(string) string; StyleDebug func(string) string; StyleInfo func(string) string; StyleWarn func(string) string; StyleError func(string) string; StyleSecurity func(string) string; /* unexported fields */ }	dappco.re/go/core/log	Concurrent-safe structured logger with overridable style hooks.	yes
Options	type Options struct { Level Level; Output io.Writer; Rotation *RotationOptions; RedactKeys []string }	dappco.re/go/core/log	Logger construction options for level, destination, rotation, and redaction.	yes
RotationOptions	type RotationOptions struct { Filename string; MaxSize int; MaxAge int; MaxBackups int; Compress bool }	dappco.re/go/core/log	Log rotation and retention policy passed to the rotation writer factory.	yes

Constants

Name	Signature	Package Path	Description	Test Coverage
LevelQuiet	const LevelQuiet Level = iota	dappco.re/go/core/log	Suppresses all log output.	yes
LevelError	const LevelError Level	dappco.re/go/core/log	Emits only error and security messages.	yes
LevelWarn	const LevelWarn Level	dappco.re/go/core/log	Emits warnings, errors, and security messages.	yes
LevelInfo	const LevelInfo Level	dappco.re/go/core/log	Emits informational, warning, error, and security messages.	yes
LevelDebug	const LevelDebug Level	dappco.re/go/core/log	Emits all log levels, including debug details.	yes

Variable

Name	Signature	Package Path	Description	Test Coverage
RotationWriterFactory	var RotationWriterFactory func(RotationOptions) io.WriteCloser	dappco.re/go/core/log	Optional injection point for creating rotating log writers.	yes

Methods

Name	Signature	Package Path	Description	Test Coverage
(*Err).Error	func (e *Err) Error() string	dappco.re/go/core/log	Formats an Err into its public error string representation.	yes
(*Err).Unwrap	func (e *Err) Unwrap() error	dappco.re/go/core/log	Returns the wrapped cause for errors.Is and errors.As.	yes
(Level).String	func (l Level) String() string	dappco.re/go/core/log	Returns the canonical lowercase name for a log level.	yes
(*Logger).SetLevel	func (l *Logger) SetLevel(level Level)	dappco.re/go/core/log	Updates the logger's active verbosity threshold.	yes
(*Logger).Level	func (l *Logger) Level() Level	dappco.re/go/core/log	Returns the logger's current verbosity threshold.	yes
(*Logger).SetOutput	func (l *Logger) SetOutput(w io.Writer)	dappco.re/go/core/log	Replaces the logger's output writer.	yes
(*Logger).SetRedactKeys	func (l *Logger) SetRedactKeys(keys ...string)	dappco.re/go/core/log	Replaces the set of keys whose values are redacted in output.	yes
(*Logger).Debug	func (l *Logger) Debug(msg string, keyvals ...any)	dappco.re/go/core/log	Emits a debug log line when the logger level allows it.	yes
(*Logger).Info	func (l *Logger) Info(msg string, keyvals ...any)	dappco.re/go/core/log	Emits an informational log line when the logger level allows it.	yes
(*Logger).Warn	func (l *Logger) Warn(msg string, keyvals ...any)	dappco.re/go/core/log	Emits a warning log line when the logger level allows it.	yes
(*Logger).Error	func (l *Logger) Error(msg string, keyvals ...any)	dappco.re/go/core/log	Emits an error log line when the logger level allows it.	yes
(*Logger).Security	func (l *Logger) Security(msg string, keyvals ...any)	dappco.re/go/core/log	Emits a security log line using the security prefix at error visibility.	yes

Functions

Name	Signature	Package Path	Description	Test Coverage
New	func New(opts Options) *Logger	dappco.re/go/core/log	Constructs a logger from the supplied options and defaults.	yes
Username	func Username() string	dappco.re/go/core/log	Returns the current system username with environment fallbacks.	yes
Default	func Default() *Logger	dappco.re/go/core/log	Returns the package-level default logger.	yes
SetDefault	func SetDefault(l *Logger)	dappco.re/go/core/log	Replaces the package-level default logger.	yes
SetLevel	func SetLevel(level Level)	dappco.re/go/core/log	Updates the package-level default logger's level.	yes
SetRedactKeys	func SetRedactKeys(keys ...string)	dappco.re/go/core/log	Updates the package-level default logger's redaction keys.	yes
Debug	func Debug(msg string, keyvals ...any)	dappco.re/go/core/log	Proxies a debug log call to the default logger.	yes
Info	func Info(msg string, keyvals ...any)	dappco.re/go/core/log	Proxies an informational log call to the default logger.	yes
Warn	func Warn(msg string, keyvals ...any)	dappco.re/go/core/log	Proxies a warning log call to the default logger.	yes
Error	func Error(msg string, keyvals ...any)	dappco.re/go/core/log	Proxies an error log call to the default logger.	yes
Security	func Security(msg string, keyvals ...any)	dappco.re/go/core/log	Proxies a security log call to the default logger.	yes
E	func E(op, msg string, err error) error	dappco.re/go/core/log	Creates an *Err with operation context and an optional wrapped cause.	yes
Wrap	func Wrap(err error, op, msg string) error	dappco.re/go/core/log	Wraps an error with operation context and preserves any existing code.	yes
WrapCode	func WrapCode(err error, code, op, msg string) error	dappco.re/go/core/log	Wraps an error with operation context and an explicit machine-readable code.	yes
NewCode	func NewCode(code, msg string) error	dappco.re/go/core/log	Creates a coded error without an underlying cause.	yes
Is	func Is(err, target error) bool	dappco.re/go/core/log	Convenience wrapper around errors.Is.	yes
As	func As(err error, target any) bool	dappco.re/go/core/log	Convenience wrapper around errors.As.	yes
NewError	func NewError(text string) error	dappco.re/go/core/log	Convenience wrapper around errors.New.	yes
Join	func Join(errs ...error) error	dappco.re/go/core/log	Convenience wrapper around errors.Join.	yes
Op	func Op(err error) string	dappco.re/go/core/log	Extracts the outermost operation name from an *Err.	yes
ErrCode	func ErrCode(err error) string	dappco.re/go/core/log	Extracts the machine-readable code from an *Err.	yes
Message	func Message(err error) string	dappco.re/go/core/log	Returns an *Err message or falls back to err.Error().	yes
Root	func Root(err error) error	dappco.re/go/core/log	Returns the deepest wrapped cause in an error chain.	yes
AllOps	func AllOps(err error) iter.Seq[string]	dappco.re/go/core/log	Returns an iterator over every non-empty operation in an error chain.	no
StackTrace	func StackTrace(err error) []string	dappco.re/go/core/log	Collects the logical stack trace of operations from an error chain.	yes
FormatStackTrace	func FormatStackTrace(err error) string	dappco.re/go/core/log	Formats the logical stack trace as a single outer -> inner string.	yes
LogError	func LogError(err error, op, msg string) error	dappco.re/go/core/log	Logs at error level and returns the wrapped error.	yes
LogWarn	func LogWarn(err error, op, msg string) error	dappco.re/go/core/log	Logs at warning level and returns the wrapped error.	yes
Must	func Must(err error, op, msg string)	dappco.re/go/core/log	Logs and panics when given a non-nil error.	yes