Skip to content
vasileskPublic

About

Attach structured key-value context to Go errors and read it back from anywhere in the error tree. Works with errors.Is/As, fmt.Errorf %w and errors.Join, plugs into log/slog. Zero dependencies.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

efmt

tag Go Version Go Reference Tests Lint Coverage License

efmt is a Go library for enhanced error handling that allows you to attach structured metadata (key-value pairs) to errors. This helps to enrich error context while maintaining compatibility with Go's standard error interface.

Installation

go get github.com/vasilesk/efmt@latest

Features

  • Create errors with structured metadata
  • Wrap existing errors with additional context
  • Extract metadata from errors as key-value pairs
  • Collect metadata from the whole error tree, including fmt.Errorf("%w") and errors.Join
  • Pass metadata to log/slog
  • Fully compatible with Go's standard error interface and unwrap mechanism
  • No dependencies outside the standard library

Usage Examples

Creating a new error with metadata

import "github.com/vasilesk/efmt"

func validateUser(user User) error {
    if user.Age < 18 {
        return efmt.New("user is underage",
            efmt.KV("user_id", user.ID),
            efmt.KV("age", user.Age),
            efmt.KV("required_age", 18),
        )
    }
    return nil
}

Wrapping an existing error

import "github.com/vasilesk/efmt"

func processRequest(req Request) error {
    user, err := fetchUser(req.UserID)
    if err != nil {
        return efmt.Wrap(err, "failed to fetch user",
            efmt.KV("request_id", req.ID),
            efmt.KV("user_id", req.UserID),
        )
    }
    // Process user...
    return nil
}

Extracting metadata from errors

import (
    "fmt"
    "github.com/vasilesk/efmt"
)

func handleError(err error) {
    // Get all key-value pairs
    allValues := efmt.Values(err)
    fmt.Printf("Error context: %+v\n", allValues)

    // Get a specific value
    if requestID, ok := efmt.Value[string](err, "request_id"); ok {
        fmt.Printf("Request ID: %s\n", requestID)
    }

    // Get all key-value pairs as a slice
    pairs := efmt.ValuePairs(err)
    for _, kv := range pairs {
        fmt.Printf("%s: %v\n", kv.Key, kv.Value)
    }
}

Working with error chains

import "github.com/vasilesk/efmt"

func processData() error {
    data, err := fetchData()
    if err != nil {
        return efmt.Wrap(err, "data fetch failed",
            efmt.KV("timestamp", time.Now()),
        )
    }

    err = validateData(data)
    if err != nil {
        return efmt.Wrap(err, "data validation failed",
            efmt.KV("data_size", len(data)),
        )
    }

    return nil
}

// Later when handling the error:
func handleProcessingError(err error) {
    // This will extract all metadata from the entire error chain
    allValues := efmt.Values(err)
    fmt.Printf("Complete error context: %+v\n", allValues)
}

Logging with slog

efmt.Attrs returns the metadata as slog attributes in a stable order:

import (
    "context"
    "log/slog"

    "github.com/vasilesk/efmt"
)

func logError(ctx context.Context, logger *slog.Logger, err error) {
    attrs := append(efmt.Attrs(err), slog.Any("error", err))
    logger.LogAttrs(ctx, slog.LevelError, "request failed", attrs...)
}

Key precedence

When the same key is set at several levels of an error tree, the outermost value wins:

inner := efmt.New("parse failed", efmt.KV("stage", "parse"), efmt.KV("line", 7))
outer := efmt.Wrap(inner, "load failed", efmt.KV("stage", "load"))

efmt.Values(outer) // map[line:7 stage:load]

ValuePairs returns all pairs, duplicates included, in traversal order: an error comes before the errors it wraps, and errors combined with errors.Join are visited in order. Values, Value and Attrs all use the first occurrence of a key in that order. Value[T] returns false if that occurrence is not of type T; it does not fall back to a shadowed inner value.

Compatibility with the errors package

efmt errors work with errors.Is, errors.As and errors.Unwrap, and metadata is collected through errors wrapped by other means:

import (
    "errors"
    "fmt"

    "github.com/vasilesk/efmt"
)

err := fmt.Errorf("handler: %w", efmt.Wrap(ErrNotFound, "lookup failed", efmt.KV("id", 42)))

errors.Is(err, ErrNotFound) // true
efmt.Values(err)            // map[id:42]

License

See the LICENSE file for details.

About

Attach structured key-value context to Go errors and read it back from anywhere in the error tree. Works with errors.Is/As, fmt.Errorf %w and errors.Join, plugs into log/slog. Zero dependencies.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages