adfer

README

This Go library provides a flexible way to handle panics across your application, including in goroutines. It allows for custom error handling, dumping errors to a file, optionally exiting the program after a panic occurs, including system information in crash reports, and managing crash reports.

Features

• Custom error handling
• Panic recovery in goroutines
• Option to dump errors to a JSON file
• Option to exit the program after handling a panic
• Option to include system information in crash reports
• Retrieve last N crash reports
• Wipe crash file on startup or initialization
• Add custom metadata to crash reports
• Easy integration with existing Go applications

Installation

go get github.com/leaanthony/adfer

Usage

Here are some examples of how to use adfer in your applications.

Basic Usage

package main

import (
    "fmt"
    "github.com/leaanthony/adfer"
)

func main() {
    // Initialize the panic handler
    ph := adfer.New()

    // Use SafeGo for goroutines
    ph.SafeGo(func() {
        // This panic will be caught and handled
        panic("oops in goroutine")
    })

    // For the main thread, use defer
    defer ph.Recover()

    // This panic will also be caught and handled
    panic("oops in main")
}

Custom Error Handler

ph := panichandler.New(panichandler.WithErrorHandler(func(err error, stack []byte) {
    fmt.Printf("Custom handler: %v\n", err)
}))

Dump to File

ph := panichandler.New(panichandler.WithDumpToFile("/path/to/panic.log"))

Exit on Panic

ph := panichandler.New(panichandler.WithExitOnPanic())

Include System Information

ph := panichandler.New(panichandler.WithSystemInfo())

Wipe Crash File on Initialization

ph := panichandler.New(panichandler.WithWipeFileOnInit())

Add Custom Metadata

ph := panichandler.New(panichandler.WithMetadata(map[string]string{
    "version": "1.2.3",
    "environment": "production",
}))

Combining Options

ph := panichandler.New(
    panichandler.WithErrorHandler(customHandler),
    panichandler.WithDumpToFile("/path/to/panic.log"),
    panichandler.WithExitOnPanic(),
    panichandler.WithSystemInfo(),
    panichandler.WithWipeFileOnInit(),
    panichandler.WithMetadata(map[string]string{
        "version": "1.2.3",
        "environment": "production",
    }),
)

Retrieving Last N Crash Reports

reports, err := ph.GetLastNCrashReports(5)
if err != nil {
    fmt.Printf("Error retrieving crash reports: %v\n", err)
} else {
    for _, report := range reports {
        fmt.Printf("Crash at %v: %s\n", report.Timestamp, report.Error)
    }
}

Wiping Crash File

err := ph.WipeCrashFile()
if err != nil {
    fmt.Printf("Error wiping crash file: %v\n", err)
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

What does the name mean?

It is Welsh for "Recover" as well as a few other meanings.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

• type CrashReport
• type ErrorHandler
• type Options
• type PanicHandler
  • func New(options Options) *PanicHandler
  • func (ph *PanicHandler) GetLastNCrashReports(n int) ([]CrashReport, error)
  • func (ph *PanicHandler) Recover()
  • func (ph *PanicHandler) SafeGo(f func())
  • func (ph *PanicHandler) WipeCrashFile() error
• type SystemInfo

Types

type CrashReport

type CrashReport struct {
	Timestamp  time.Time         `json:"timestamp"`
	Error      string            `json:"error"`
	Stack      string            `json:"stack"`
	SystemInfo SystemInfo        `json:"system_info,omitempty"`
	Metadata   map[string]string `json:"metadata,omitempty"`
}

CrashReport represents a single crash report

type ErrorHandler

type ErrorHandler func(error, []byte)

ErrorHandler is a function type for custom error handling

type Options

type Options struct {
	// ErrorHandler is a custom error handling function
	ErrorHandler ErrorHandler
	// DumpToFile enables dumping errors to a file
	DumpToFile bool
	// FilePath is the path to the file to dump errors to
	FilePath string
	// ExitOnPanic enables exiting the program after handling a panic
	ExitOnPanic bool
	// IncludeSystemInfo enables including system information in crash reports
	IncludeSystemInfo bool
	// Metadata is custom metadata to include in crash reports
	Metadata map[string]string
	// WipeFile enables wiping the crash file on initialization
	WipeFile bool
}

Options struct holds the configuration for panic handling

type PanicHandler

type PanicHandler struct {
	// contains filtered or unexported fields
}

func New

func New(options Options) *PanicHandler

New initializes a new PanicHandler with optional configurations

func (*PanicHandler) GetLastNCrashReports

func (ph *PanicHandler) GetLastNCrashReports(n int) ([]CrashReport, error)

GetLastNCrashReports retrieves the last N crash reports from the log file

func (*PanicHandler) Recover

func (ph *PanicHandler) Recover()

Recover is the main function to recover from panics

func (*PanicHandler) SafeGo

func (ph *PanicHandler) SafeGo(f func())

SafeGo wraps a function to be executed in a goroutine with panic recovery

func (*PanicHandler) WipeCrashFile

func (ph *PanicHandler) WipeCrashFile() error

WipeCrashFile clears all crash reports from the log file

type SystemInfo

type SystemInfo struct {
	OS           string `json:"os"`
	Architecture string `json:"architecture"`
	GoVersion    string `json:"go_version"`
}

SystemInfo represents system information