errors

README

errors

github.com/zenact-ai/errors adds stack capture, structured attributes, typed-error detail rendering, and structured logging to Go error chains while preserving standard errors.Is, errors.As, and errors.Join behavior.

result, err := client.Fetch(ctx, id)
if err != nil {
	return errors.Wrap(
		err,
		errors.Stackf("fetch record"),
		errors.String("record_id", id),
	)
}

Typed errors can implement ErrorDetails() errors.Details to expose bounded, ordered diagnostic facts. Classification remains based on concrete error types and sentinels through errors.As and errors.Is; semantic detail strings are for observability only. See ERROR_DETAILS.md for the full contract.

Documentation

Index

• func As(err error, target interface{}) bool
• func Errorf(format string, args ...interface{}) error
• func FormatErrorContext(err error) string
• func FormatErrorDetails(err error) string
• func FormatErrorStack(err error) string
• func Is(err, target error) bool
• func Join(errs ...error) error
• func New(message string, attrs ...ErrorAttribute) error
• func Report(ctx context.Context, err error)
• func ReportWithSeverity(ctx context.Context, err error, severity Severity)
• func SlogErr(err error) slog.Attr
• func Wrap(err error, attrs ...ErrorAttribute) error
• func WrapStackf(err error, format string, args ...interface{}) error
• func WrapWithStack(err error, stackattr ErrorAttribute, attrs ...ErrorAttribute) error
• type AttributeType
• type Detail
• type Details
• type ErrorAttribute
  • func Int(key string, value int) ErrorAttribute
  • func Int64(key string, value int64) ErrorAttribute
  • func KeyedStackf(key, format string, args ...interface{}) ErrorAttribute
  • func Stackf(format string, args ...interface{}) ErrorAttribute
  • func String(key, value string) ErrorAttribute
  • func StringPtr(key string, value *string) ErrorAttribute
  • func Stringf(key, format string, args ...interface{}) ErrorAttribute
  • func Uint64(key string, value uint64) ErrorAttribute
• type ErrorAttributes
  • func (attrs ErrorAttributes) ErrorAttributes() map[string]interface{}
  • func (attrs ErrorAttributes) SlogAttrs() []slog.Attr
• type ErrorDetailer
• type ErrorMessage
  • func (e ErrorMessage) Error() string
• type Severity
  • func (s Severity) String() string
• type WrapConfig

Functions

func As

func As(err error, target interface{}) bool

func Errorf

func Errorf(format string, args ...interface{}) error

func FormatErrorContext

func FormatErrorContext(err error) string

FormatErrorContext renders only explicit Stackf operation breadcrumbs from the complete error chain. It does not include semantic details or frames.

func FormatErrorDetails

func FormatErrorDetails(err error) string

FormatErrorDetails renders a deterministic, bounded semantic cause trace. It supports both single-cause chains and joined errors and never mutates the supplied error values.

func FormatErrorStack

func FormatErrorStack(err error) string

FormatErrorStack renders captured runtime frames from the complete error chain. It does not include semantic details or operation breadcrumbs.

func Is

func Is(err, target error) bool

func Join

func Join(errs ...error) error

func New

func New(message string, attrs ...ErrorAttribute) error

func Report

func Report(ctx context.Context, err error)

func ReportWithSeverity

func ReportWithSeverity(ctx context.Context, err error, severity Severity)

func SlogErr

func SlogErr(err error) slog.Attr

func Wrap

func Wrap(err error, attrs ...ErrorAttribute) error

func WrapStackf

func WrapStackf(err error, format string, args ...interface{}) error

func WrapWithStack

func WrapWithStack(err error, stackattr ErrorAttribute, attrs ...ErrorAttribute) error

Types

type AttributeType

type AttributeType uint8

const (
	UnknownAttributeType AttributeType = iota
	StringAttributeType
	Uint64AttributeType
	Int64AttributeType
	StackAttributeType
	StringPtrAttributeType
	NoOpStackAttributeType
)

type Detail

type Detail struct {
	Key   string
	Value string
}

Detail is one safe, ordered diagnostic field exposed by a typed error. Keys should use [a-z][a-z0-9_.]*. Values must not contain secrets or other data that is unsafe to publish to observability systems.

type Details

type Details struct {
	Type   string
	Fields []Detail
}

Details is a typed error's semantic observability projection. Type is a stable snake_case identity; it is not derived from a Go type name. Fields retain their declaration order.

type ErrorAttribute

type ErrorAttribute struct {
	// contains filtered or unexported fields
}

func Int

func Int(key string, value int) ErrorAttribute

func Int64

func Int64(key string, value int64) ErrorAttribute

func KeyedStackf

func KeyedStackf(key, format string, args ...interface{}) ErrorAttribute

func Stackf

func Stackf(format string, args ...interface{}) ErrorAttribute

func String

func String(key, value string) ErrorAttribute

func StringPtr

func StringPtr(key string, value *string) ErrorAttribute

func Stringf

func Stringf(key, format string, args ...interface{}) ErrorAttribute

func Uint64

func Uint64(key string, value uint64) ErrorAttribute

type ErrorAttributes

type ErrorAttributes []ErrorAttribute

func (ErrorAttributes) ErrorAttributes

func (attrs ErrorAttributes) ErrorAttributes() map[string]interface{}

func (ErrorAttributes) SlogAttrs

func (attrs ErrorAttributes) SlogAttrs() []slog.Attr

type ErrorDetailer

type ErrorDetailer interface {
	ErrorDetails() Details
}

ErrorDetailer exposes safe semantic facts for diagnostic rendering. Application control flow should continue to classify errors with Is and As against concrete sentinels and types, not with Details.Type.

type ErrorMessage

type ErrorMessage string

func (ErrorMessage) Error

func (e ErrorMessage) Error() string

type Severity

type Severity string

const (
	SeverityWarning Severity = "Warning"
	SeverityError   Severity = "Error"
)

func (Severity) String

func (s Severity) String() string

type WrapConfig

type WrapConfig struct {
	Error      error
	Stack      ErrorAttribute
	Attributes []ErrorAttribute
}