Structured Errors in Go (2022)

Structured Errors in Go (2022)
southcla.ws

Edit: looking more carefully at the lib I assume that ”tag” is the concept that is supposed to cover this?

An additional thing that is useful here would be a stack trace. So even when you catch, wrap & rethrow the error, you'll be able to see exactly where the error came from. The alternative is searching in the code for the string.

For the hate they seem to get, checked exceptions with error classes do give you a lot of stuff for free.

The way to do this in a safe and performant manner is to structure the metadata as a tree, with a parent pointing to the previous metadata. You'd probably want to do some pooling and other optimizations to avoid allocating a map every time. Then all the maps can be immutable and therefore not require any locks. To construct the final map at error time, you simply traverse the map depth-first, building a merged map.

I'm not sure I agree with the approach, however. This system will incur a performance and memory penalty every time you descend into a new metadata context, even when no errors are occurring. Building up this contextual data (which presumably already exists on the call stack in the form of local variables) will be constantly going on and causing trouble in hot paths.

A better approach is to return a structured error describing the failed action that includes data known to the returner, which should have enough data to be meaningful. Then, every time you pass an error up the stack, you augment it with additional data so that everything can be gleaned from it. Rather than:

    val, err := GetStuff()
    if err != nil {
      return err
    }

    val, err := GetStuff()
    if err != nil {
      return fmt.Errorf("getting stuff: %w")
    }

    val, err := GetStuff()
    if err != nil {
      return wrapWithMetadata(err, meta.KV("database", db.Name))
    }

This pays the performance cost only at error time, and the contextual information travels up the stack with a tree of error causes that can be gotten with `errors.Unwrap()`. The point is that Go errors already are a tree of causes.

Sometimes tracking contextual information in a context is useful, of course. But I think the benefit of my approach is that a function returning an error only needs to provide what it knows about the failing error. Any "ambient" contextual information can be added by the caller at no extra cost when following the happy path.

The idea is to only add information that the caller isn't already aware of. Error messages shouldn't include the function name or any of its arguments, because the caller will include those in its own wrapping of that error.

This is done with fmt.Errorf():

    userId := "A0101"
    err := database.Store(userId);
    if err != nil {
        return fmt.Errorf("database.Store({userId: %q}): %w", userId, err)
    }

    fmt.Printf("ERROR %v\n", err)

    ERROR app.run(): room.start({name: "participant5"}): UseStorage({type: "sqlite"}): Store({userId: "A0101"}): the transaction was interrupted

Of course, longer error messages could be written, but it seems optimal to just convey a minimal expression of what function call and argument was being called when the error happened.

Adding to this, the Go code linter forbids writing error messages that start with Upper Case, precisely because it assumes that all this will be done and error messages are just parts of a longer sentence:

https://staticcheck.dev/docs/checks/#ST1005