oops

Oops provides rich, structured error data that can be exported in multiple formats. This data includes error codes, domain-specific tags, execution context (like user IDs), hints for troubleshooting (e.g., runbook links), and detailed stacktraces.

When using Oops with loggers, you can expect outputs in formats like plain text (for human readability) or JSON (for machine processing and observability platforms).

{
  "code": "iam_missing_permission",
  "context": {
    "user_id": 1234
  },
  "domain": "authz",
  "tags": [
    "iam",
    "authz"
  ],
  "error": "Permission denied",
  "hint": "Runbook: https://doc.acme.org/doc/abcd.md",
  "time": "2023-05-02T05:26:48.570837Z",
  "duration": "42ms",
  "stacktrace": "Oops: permission denied\n  --- at github.com/samber/oops/loggers/slog/example.go:20 (d)",
  "trace": "4ab0e35e-8414-4d76-b09e-cba80c983e4b",
  "user": {
    "firstname": "john",
    "id": "user-123",
    "lastname": "doe"
  }
}

When deciding between standard Go error handling and Oops, consider the following trade-offs:

Standard Go Errors

Best for: Simple, lightweight applications with no external dependencies where performance is critical and context requirements are minimal.

• Pros: Minimal overhead, familiar syntax, no dependencies.
• Cons: No structured attributes, manual stack trace management, difficult to propagate rich context across layers.

Oops Error Handling

Best for: Complex applications requiring rich contextual information, structured logging, and easy debugging.

• Pros: Automatic stacktraces, fluent builder pattern, structured attributes (tags, codes, hints), and easy integration with loggers.
• Cons: Adds an external dependency and is slightly more verbose than standard errors.

// Standard Go Example
func processUser(userID int) error {
    if userID <= 0 {
        return fmt.Errorf("invalid user ID: %d", userID)
    }
    
    if err := databaseOperation(userID); err != nil {
        return fmt.Errorf("failed to process user %d: %w", userID, err)
    }
    
    return nil
}

// Oops Example
func processUser(userID int) error {
    if userID <= 0 {
        return oops.
            Code("invalid_user_id").
            In("user_processing").
            Tags("validation", "user").
            With("user_id", userID).
            Hint("User ID must be a positive integer").
            Errorf("invalid user ID: %d", userID)
    }
    
    if err := databaseOperation(userID); err != nil {
        return oops.
            In("user_processing").
            Tags("database", "user").
            With("user_id", userID).
            Wrapf(err, "failed to process user %d", userID)
    }
    
    return nil
}

Oops uses a fluent builder pattern to construct rich, structured errors. Instead of creating a simple error with errors.New, you chain methods on the oops builder to attach context like error codes, domains, tags, and custom attributes. This allows you to build highly descriptive errors that are useful for both structured logging and debugging.

Commonly used methods include:

• Code(code any): Sets a machine-readable error code.
• In(domain string): Sets the error domain.
• Tags(tags ...string): Adds categorization tags.
• With(kv ...any): Adds arbitrary key-value pairs as attributes.
• Hint(hint string): Provides a human-readable hint for resolution.
• Errorf(format string, args ...any): Finalizes the builder and returns the error.

err := oops.
    Code("auth_failed").
    In("authentication").
    Tags("security", "auth").
    With("user_id", 123).
    Hint("Check user permissions").
    Errorf("authentication failed")

To maintain a predictable API and error handling logic, define error codes as constants. Use the oops.Code(string) method to attach these codes to errors. This allows consumers to programmatically identify the type of error (e.g., auth_failed, validation_failed) without parsing error strings.

When creating errors, combine Code() with other context methods like In(), Tags(), and With() to provide a rich, structured error object.

// Define error codes as constants
const (
    ErrCodeAuthFailed       = "auth_failed"
    ErrCodeValidationFailed = "validation_failed"
    ErrCodeDatabaseError    = "database_error"
    ErrCodeNetworkTimeout   = "network_timeout"
    ErrCodeFileNotFound     = "file_not_found"
    ErrCodePermissionDenied = "permission_denied"
)

func authenticateUser(username, password string) error {
    if username == "" {
        return oops.
            Code(ErrCodeValidationFailed).
            In("authentication").
            Tags("auth", "validation").
            With("field", "username").
            Hint("Username is required").
            Errorf("missing username")
    }
    
    return oops.
        Code(ErrCodeAuthFailed).
        In("authentication").
        Tags("auth", "security").
        With("username", username).
        Hint("Check credentials").
        Public("Invalid username or password").
        Errorf("authentication failed for user %s", username)
}