go-samber-oops

samber/oops — Structured Errors

Upstream: https://github.com/samber/oops

What Stdlib Doesn't Give You

fmt.Errorf("ctx: %w", err) gives you: a message, an unwrap chain. That's it. It does NOT give: stack traces, domain codes, request IDs, user-facing hints, owner/team routing, key-value context. oops adds those via a builder API, staying compatible with errors.Is / errors.As.

Core API

import "github.com/samber/oops"

// Create
err := oops.
    Code("USER_NOT_FOUND").
    In("UserService.FindByID").
    With("user_id", userID).
    Errorf("user %d not found", userID)

// Wrap — add attributes to existing error
err := oops.
    In("OrderService.Create").
    With("order_id", orderID).
    Wrap(repoErr)

// Wrap with a fresh message
err := oops.Trace(traceID).Wrapf(repoErr, "could not persist order %d", orderID)

Builder methods return OopsErrorBuilder; call Errorf / Wrap / Wrapf / New last.

Attributes

Method	Purpose	APM field
.Code("X")	Stable domain key	error.code
.In("pkg.Service.Method")	Subsystem	error.domain
.Tags("auth", "critical")	Free-form labels	error.tags
.With("key", v)	Structured context	error.context.*
.User(id, "email", x)	User identity	user.*
.Tenant(id, ...)	Tenant identity	tenant.*
.Request(req)	HTTP request capture	http.*
.Trace(traceID)	Tracing correlation	trace.id
.Hint("...")	Operator remediation	error.hint
.Public("...")	User-safe HTTP body	error.public_message
.Owner("team")	Alert routing	error.owner
.Duration(d)	Op duration	error.duration_ms

Stack Traces

Captured automatically at the first Errorf/Wrap/Wrapf/New in a chain — not at every wrap. Depth cap: oops.StackTraceMaxDepth (default 10). Set to 0 to disable on hot paths.

Extraction for Logging / APM

import (
    "errors"
    "log/slog"
    "github.com/samber/oops"
)

func logError(err error) {
    var oe oops.OopsError
    if errors.As(err, &oe) {
        slog.Error("operation failed",
            "code", oe.Code(),
            "domain", oe.Domain(),
            "tags", oe.Tags(),
            "context", oe.Context(),
            "hint", oe.Hint(),
            "owner", oe.Owner(),
            "user", oe.User(),
            "trace_id", oe.Trace(),
            "stacktrace", oe.Stacktrace(),
            "error", err,
        )
        return
    }
    slog.Error("operation failed", "error", err)
}

// Or: slog.Error("failed", slog.Any("error", oops.ToMap(err)))