266 lines
10 KiB
Markdown
266 lines
10 KiB
Markdown
# 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 `<nil>`, 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.
|