samber / oops

Oops - Structured Error Handling for Go > **Transform your Go error handling from "oops!" to "aha!" moments** **Oops** is a comprehensive Go error handling library that provides structured error management with rich contextual information. It's designed as a drop-in replacement for Go's built-in , adding powerful features like stack traces, source code fragments, structured attributes, and developer-friendly debugging hints. **🎯 Key Features:** • **🔧 Drop-in Replacement**: Seamlessly replaces standard Go error handling • **📊 Rich Context**: Add structured attributes, user info • **🐛 Debug-Friendly**: Out-of-the-box stacktraces and source code fragments • **🔗 Error Chaining**: Wrap and compose errors with additional context • **🛡️ Panic Recovery**: Built-in panic handling with error conversion • **✅ Assertions**: One-line assertion helpers for validation • **⚡ Performance**: Zero dependencies, lightweight and fast • **📝 Logger Integration**: Works with all major Go logging libraries • **✂️ Separation of Concerns**: Error handling and logging are separate jobs • **🍳 Easy Integration**: No large refactoring required > [!WARNING] > **Important**: This is NOT a logging library. should complements your existing logging toolchain (zap, zerolog, logrus, slog, go-sentry...). 🥷 Start hacking with this playground. Sponsored by: Cut Kubernetes & AI costs, boost application stability 100% OpenTelemetry-native observability platform Simple to use, built on open standards, and designed for full cost control **Table of content** • 🚀 Install • 💡 Quick start • 🧠 Spec • Error builder • Context • Other helpers • Stack trace • Source fragments • Panic handling • Assertions • Output • Go context • 📫 Loggers • 🥷 Tips and best practices Context rich error handling In a few minutes, your logs will look like this: 🚀 Install This library is v1 and follows SemVer strictly. No breaking changes will be made to APIs before v2.0.0. This library has no dependencies outside the Go standard library. 💡 Quick start This library provides a simple builder for composing structured errors, with contextual attributes and stack trace. Since implements the interface, you will be able to compose and wrap native errors with . 🧠 Spec GoDoc: https://godoc.org/github.com/samber/oops Error builder | Method | Description | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | | Formats returns object that satisfies | | | Formats an error and returns object that satisfies | | | Wraps an error into an object that satisfies | | | Wraps an error into an object that satisfies and formats an error message | | | Handle panic and returns object that satisfies . | | | Handle panic and returns object that satisfies and formats an error message. | | | Panics if condition is false. Assertions can be chained. | | | Panics if condition is false and formats an error message. Assertions can be chained. | | | Join returns an error that wraps the given errors. | Examples Context The library provides an error builder. Each method can be used standalone (eg: ) or from a previous builder instance (eg: ). The builder must finish with either , , , , or . | Builder method | Getter | Description | | --------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | | Supply a list of attributes key+value. Values of type are accepted and evaluated lazily. | | | | Supply a list of values declared in context. Values of type are accepted and evaluated lazily. | | | | Set a code or slug that describes the error. Error messages are intended to be read by humans, but such code is expected to be read by machines and be transported over different services | | | | Set a message that is safe to show to an end user | | | | Set the error time (default: ) | | | | Set the error duration | | | | Set the error duration | | | | Set the feature category or domain | | | | Add multiple tags, describing the feature returning an error | | | | Check whether the error contains provided tag | | | | Add a transaction id, trace id, correlation id... (default: ULID) | | | | Add a span representing a unit of work or operation... (default: ULID) | | | | Set a hint for faster debugging | | | | Set the name/email of the colleague/team responsible for handling this error. Useful for alerting purpose | | | | Supply user id and a chain of key/value | | | | Supply tenant id and a chain of key/value | | | | Supply http request | | | | Supply http response | | | | Reuse an existing OopsErrorBuilder transported in a Go context | Examples Other helpers • as an alias to Stack trace This library provides a pretty printed stack trace for each generated error. The stack trace max depth can be set using: The stack trace will be printed this way: Wrapped errors will be reported as an annotated stack trace: Source fragments The exact error location can be provided in a Go file extract. Source fragments are hidden by default. You must run to enable this feature. Go source files being read at run time, you have to keep the source code at the same location. In a future release, this library is expected to output a colorized extract. Please contribute! Panic handling library is delivered with a try/catch -ish error handler. 2 handlers variants are available: and . Both can be used in the error builder with usual methods. 🥷 Start hacking with this playground. Assertions Assertions may be considered an anti-pattern for Golang since we only call for unexpected and critical errors. In this situation, assertions might help developers to write safer code. Output Errors can be printed in many ways. Logger formatters provid…