# log **Import:** `dappco.re/go/core/log` **Files:** 2 ## Types ### Err `type Err struct` Structured error wrapper that carries operation context, a human-readable message, an optional wrapped cause, and an optional machine-readable code. It can also carry agent-facing recovery metadata that survives wrapping and is surfaced automatically in structured logs. Fields: - `Op string`: operation name. When non-empty, `Error` prefixes the formatted message with `Op + ": "`. - `Msg string`: human-readable message stored on the error and returned by `Message`. - `Err error`: wrapped cause returned by `Unwrap`. - `Code string`: optional machine-readable code. When non-empty, `Error` includes it in square brackets. - `Retryable bool`: whether the caller can safely retry the operation. - `RetryAfter *time.Duration`: optional retry delay hint when `Retryable` is true. - `NextAction string`: suggested next step when the error is not directly retryable. Methods: - `func (e *Err) Error() string`: formats the error text from `Op`, `Msg`, `Code`, and `Err`. The result omits missing parts, so the output can be `"{Msg}"`, `"{Msg} [{Code}]"`, `"{Msg}: {Err}"`, `"{Op}: {Msg} [{Code}]: {Err}"`, or a cleanly collapsed form such as `"{Op}"` when no message, code, or cause is present. - `func (e *Err) Unwrap() error`: returns `e.Err`. ### Level `type Level int` Logging verbosity enum used by `Logger` and `Options`. Methods: - `func (l Level) String() string`: returns `quiet`, `error`, `warn`, `info`, or `debug`. Any other value returns `unknown`. ### Logger `type Logger struct` Concurrency-safe structured logger. `New` clones the configured redaction keys, stores the configured level and writer, and initializes all style hooks to identity functions. Each log call writes one line in the form `HH:MM:SS {prefix} {msg}` followed by space-separated key/value pairs. String values are rendered with Go `%q` quoting, redacted keys are replaced with `"[REDACTED]"`, a trailing key without a value renders as ``, and any `error` value in `keyvals` can cause `op`, `stack`, `retryable`, `retry_after_seconds`, and `next_action` fields to be appended automatically if those keys were not already supplied. Fields: - `StyleTimestamp func(string) string`: transforms the rendered `HH:MM:SS` timestamp before it is written. - `StyleDebug func(string) string`: transforms the debug prefix passed to debug log lines. - `StyleInfo func(string) string`: transforms the info prefix passed to info log lines. - `StyleWarn func(string) string`: transforms the warn prefix passed to warning log lines. - `StyleError func(string) string`: transforms the error prefix passed to error log lines. - `StyleSecurity func(string) string`: transforms the security prefix passed to security log lines. Methods: - `func (l *Logger) SetLevel(level Level)`: sets the logger’s current threshold. - `func (l *Logger) Level() Level`: returns the logger’s current threshold. - `func (l *Logger) SetOutput(w goio.Writer)`: replaces the writer used for future log lines. - `func (l *Logger) SetRedactKeys(keys ...string)`: replaces the exact-match key list whose values are masked during formatting. - `func (l *Logger) Debug(msg string, keyvals ...any)`: emits a debug line when the logger level is at least `LevelDebug`. - `func (l *Logger) Info(msg string, keyvals ...any)`: emits an info line when the logger level is at least `LevelInfo`. - `func (l *Logger) Warn(msg string, keyvals ...any)`: emits a warning line when the logger level is at least `LevelWarn`. - `func (l *Logger) Error(msg string, keyvals ...any)`: emits an error line when the logger level is at least `LevelError`. - `func (l *Logger) Security(msg string, keyvals ...any)`: emits a security line with the security style prefix and the same visibility threshold as `LevelError`. ### Options `type Options struct` Constructor input for `New`. Fields: - `Level Level`: initial logger threshold. - `Output goio.Writer`: destination used when rotation is not selected. - `Rotation *RotationOptions`: optional rotation configuration. `New` uses rotation only when this field is non-nil, `Rotation.Filename` is non-empty, and `RotationWriterFactory` is non-nil. - `RedactKeys []string`: keys whose values should be masked in formatted log output. ### RotationOptions `type RotationOptions struct` Rotation configuration passed through to `RotationWriterFactory` when `New` selects a rotating writer. Fields: - `Filename string`: log file path. `New` only attempts rotation when this field is non-empty. - `MaxSize int`: value forwarded to the rotation writer factory. - `MaxAge int`: value forwarded to the rotation writer factory. - `MaxBackups int`: value forwarded to the rotation writer factory. - `Compress bool`: value forwarded to the rotation writer factory. ## Functions ### AllOps `func AllOps(err error) iter.Seq[string]` Returns an iterator over non-empty `Op` values found by repeatedly calling `errors.Unwrap` on `err`. Operations are yielded from the outermost `*Err` to the innermost one. ### As `func As(err error, target any) bool` Thin wrapper around `errors.As`. ### Debug `func Debug(msg string, keyvals ...any)` Calls `Default().Debug(msg, keyvals...)`. ### Default `func Default() *Logger` Returns the package-level default logger. The package initializes it with `New(Options{Level: LevelInfo})`. ### E `func E(op, msg string, err error) error` Returns `&Err{Op: op, Msg: msg, Err: err}` as an `error`. It always returns a non-nil error value, even when `err` is nil. ### EWithRecovery `func EWithRecovery(op, msg string, err error, retryable bool, retryAfter *time.Duration, nextAction string) error` Returns `&Err{Op: op, Msg: msg, Err: err}` with explicit recovery metadata attached to the new error value. ### ErrCode `func ErrCode(err error) string` If `err` contains an `*Err`, returns its `Code`. Otherwise returns the empty string. ### Error `func Error(msg string, keyvals ...any)` Calls `Default().Error(msg, keyvals...)`. ### FormatStackTrace `func FormatStackTrace(err error) string` Collects `AllOps(err)` and joins the operations with `" -> "`. Returns the empty string when no operations are found. ### Info `func Info(msg string, keyvals ...any)` Calls `Default().Info(msg, keyvals...)`. ### Is `func Is(err, target error) bool` Thin wrapper around `errors.Is`. ### Join `func Join(errs ...error) error` Thin wrapper around `errors.Join`. ### IsRetryable `func IsRetryable(err error) bool` Returns whether the first matching `*Err` in the chain is marked retryable. ### NewCodeWithRecovery `func NewCodeWithRecovery(code, msg string, retryable bool, retryAfter *time.Duration, nextAction string) error` Returns `&Err{Msg: msg, Code: code}` with recovery metadata attached. ### LogError `func LogError(err error, op, msg string) error` If `err` is nil, returns nil. Otherwise wraps the error with `Wrap(err, op, msg)`, logs `msg` through the default logger at error level with key/value pairs `"op", op, "err", err`, and returns the wrapped error. ### LogWarn `func LogWarn(err error, op, msg string) error` If `err` is nil, returns nil. Otherwise wraps the error with `Wrap(err, op, msg)`, logs `msg` through the default logger at warn level with key/value pairs `"op", op, "err", err`, and returns the wrapped error. ### Message `func Message(err error) string` Returns the `Msg` field from the first matching `*Err`. If `err` is nil, returns the empty string. For non-`*Err` errors, returns `err.Error()`. ### Must `func Must(err error, op, msg string)` If `err` is nil, does nothing. Otherwise logs `msg` through the default logger at error level with key/value pairs `"op", op, "err", err`, then panics with `Wrap(err, op, msg)`. ### New `func New(opts Options) *Logger` Constructs a logger from `opts`. It prefers a rotating writer only when `opts.Rotation` is non-nil, `opts.Rotation.Filename` is non-empty, and `RotationWriterFactory` is set; otherwise it uses `opts.Output`. If neither path yields a writer, it falls back to `os.Stderr`. ### NewCode `func NewCode(code, msg string) error` Returns `&Err{Msg: msg, Code: code}` as an `error`. ### RecoveryAction `func RecoveryAction(err error) string` Returns the first next-action hint from the error chain. ### RetryAfter `func RetryAfter(err error) (*time.Duration, bool)` Returns the first retry-after hint from the error chain, if present. ### NewError `func NewError(text string) error` Thin wrapper around `errors.New`. ### Op `func Op(err error) string` If `err` contains an `*Err`, returns its `Op`. Otherwise returns the empty string. ### Root `func Root(err error) error` Repeatedly unwraps `err` with `errors.Unwrap` until no further wrapped error exists, then returns the last error in that chain. If `err` is nil, returns nil. ### Security `func Security(msg string, keyvals ...any)` Calls `Default().Security(msg, keyvals...)`. ### SetDefault `func SetDefault(l *Logger)` Replaces the package-level default logger with `l`. ### SetLevel `func SetLevel(level Level)` Calls `Default().SetLevel(level)`. ### SetRedactKeys `func SetRedactKeys(keys ...string)` Calls `Default().SetRedactKeys(keys...)`. ### StackTrace `func StackTrace(err error) []string` Collects `AllOps(err)` into a slice in outermost-to-innermost order. When no operations are found, the returned slice is nil. ### Username `func Username() string` Returns the current username by trying `user.Current()` first, then the `USER` environment variable, then the `USERNAME` environment variable. ### Warn `func Warn(msg string, keyvals ...any)` Calls `Default().Warn(msg, keyvals...)`. ### Wrap `func Wrap(err error, op, msg string) error` If `err` is nil, returns nil. Otherwise returns a new `*Err` containing `op`, `msg`, and `err`. If the wrapped error chain already contains an `*Err` with a non-empty `Code`, the new wrapper copies that code. ### WrapCodeWithRecovery `func WrapCodeWithRecovery(err error, code, op, msg string, retryable bool, retryAfter *time.Duration, nextAction string) error` Returns nil only when both `err` is nil and `code` is empty. Otherwise it returns a wrapped `*Err` with explicit recovery metadata attached. ### WrapCode `func WrapCode(err error, code, op, msg string) error` Returns nil only when both `err` is nil and `code` is empty. In every other case it returns `&Err{Op: op, Msg: msg, Err: err, Code: code}` as an `error`. ### WrapWithRecovery `func WrapWithRecovery(err error, op, msg string, retryable bool, retryAfter *time.Duration, nextAction string) error` Returns nil when `err` is nil. Otherwise it returns a wrapped `*Err` with explicit recovery metadata attached.