Stop Guessing, Start Knowing: Error Tracking and Reporting in Go with errx

Are you tired of wrestling with cryptic error messages in your Go applications? Do you want a simple, intuitive way to track and understand errors without sacrificing performance? The errx library offers a powerful solution using statically defined stamps or trace IDs, streamlining your error reporting process. Learn how to implement this with these simple steps.

What is errx and Why Should You Care?

Error handling in Go is a hot topic, but everyone agrees on one thing: detailed error reporting is crucial. Developers need to know not just what went wrong, but where and why. errx provides a way to achieve this through unique identifiers or "stamps," offering a superior alternative to traditional stack traces. Think of Stamps as a way to put breadcrumbs in your code, leading you back to the exact point of failure efficiently.

This method offers several awesome benefits:

• Quickly pinpoint errors: Stamps are unique identifiers that instantly show you where an error originated.
• Improve application stability: Better error tracking leads to faster debugging and more reliable software.
• Boost development efficiency: Spend less time deciphering errors and more time building features.

What Makes a Good Error Handling System?

A robust error handling system should tell a story. At minimum it must include the following characteristics:

• Clear Message: A description of what happened.
• Precise Location: Stack trace, unique identifiers, or human-readable texts indicate where it happened.
• Error Type: Categorization for efficient handling and routing.
• Relevant Data: Access to useful information for processing the error.

Getting Started with errx

Installation is a breeze. Open your terminal and run:

go get -u github.com/michaelolof/errx

Now you're ready to start creating and wrapping errors with stamps!

Creating and Wrapping Errors with errx Statically Defined Stamps

Here's how you can create a new error using errx:

import "github.com/michaelolof/errx"

func failerOne() error {
    return errx.New(1745397000, "something went wrong")
}

This generates an error message like this one:

[ts 1745397000] something went wrong

Need to decorate an existing error? Use the Wrap function:

import "github.com/michaelolof/errx"

func failerTwo() error {
    err := failerOne()
    if err != nil {
        return errx.Wrap(1745397994, err)
    }
    return nil
}

The result? A chained error message like this:

[ts 1745397994]; [ts 1745397000] something went wrong

Note: errx enforces that stamps passed to New or Wrap are literal integers. Dynamic values won't work.

Classify Errors with Error Kinds and Data Kinds

Sometimes, you need to categorize errors based on your application's logic. errx lets you do this with error kinds and data kinds.

var (
	NotFoundErr = errx.Kind("notfound")
	InvalidNoErr = errx.DataKind[int]("invalidno")
)

Here's how to incorporate those error kinds:

import "github.com/michaelolof/errx"

func failerOne() error {
    return errx.NewKind(1745397000, "something went wrong", NotFoundErr)
}

func failerTwo() error {
    var v int = 2
    err := failerOne()
    if err != nil {
        return errx.WrapKind(1745397994, err, InvalidNoErr(v))
    }
    return nil
}

This results in an error message packed with even more information:

[ts 1745397994 kind invalidno data 2]; [ts 1745397000 kind notfound] something went wrong

Now, utilize these error kinds to make decisions within your code:

if errx.IsKind(err, NotFoundErr) {
    // Handle "notfound" error
}

if errx.IsDataKind(err, InvalidNoErr) {
    // Handle "invalidno" error
}

Accessing Data Kinds

Need to access data associated with a specific data kind? Use the FindData function:

if v, ok := errx.FindData(err, InvalidNoErr); ok {
	fmt.Println(v) // v is int(2)
}

The Power of Stamps: Why Use errx for Go Error Tracking and Reporting?

You might be wondering, Why stamps? Why not stick with stack traces, despite the reflection overhead? Here's why stamps offer a compelling alternative when reporting Go errors:

• Simplicity: Stamps are straightforward to implement.
• Uniqueness: Stamps provide unique identifiers for tracing.
• Efficiency: Stamps are shorter and more compact than file paths and line numbers.
• Context-independence: Stamps are immune to code changes and refactoring.
• Log-Friendliness: Stamps are easy to log and analyze.
• Client-Safe: Stamps can be safely exposed in API responses.
• Performance: Stamps avoid runtime reflection, eliminating performance penalties.
• Speedy Generation: Editor snippets make generating stamps quick and easy.

errx structures all error information (stamp, kind, data, message) within the error string. This comprehensive string allows you to fully understand the error, and even reconstruct the error object using ParseStampedError.

Maximize the Power of errx: Error handling best practices

Ultimately, knowing when to use an error kind is crucial. Use them when you need to make a decision based on the error type later in your application. If you solely need to create or wrap errors in the moment, stick to basic error creation and wrapping without defining kinds.

Ready to level up your Go error handling? Embrace errx and experience the benefits of clear, efficient, and performant error reporting.