Documentation
¶
Overview ¶
Package interruption provides a simple mechanism for recovering from panics in both the main application and concurrently running goroutines.
It ensures that unexpected runtime panics do not crash the application silently, by logging detailed error messages and stack traces.
Usage: Call `defer interruption.Handle()` at the beginning of the `main` function and in every goroutine to catch and log panics.
Example:
package main
import (
"github.com/valentin-kaiser/go-core/interruption"
"fmt"
)
func main() {
defer interruption.Handle()
fmt.Println("Application started")
// Your application logic here
ctx := interruption.OnSignal([]func() error{
func() error {
fmt.Println("Received interrupt signal, shutting down gracefully")
return nil
},
}, os.Interrupt, syscall.SIGTERM)
<-ctx.Done() // Wait for the signal handler to complete
}
In debug mode, a full stack trace is logged to aid in debugging. In production mode, only the panic message and caller information are logged to avoid cluttering logs with excessive detail.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Format specifies the timestamp format used for naming panic log files. Format = "2006-01-02_15-04-05" // Write determines whether panic information should be written to files. Write = false // Directory specifies the directory where panic log files are stored. Directory = filepath.Join(flag.Path, "panics") )
Functions ¶
func Catch ¶
func Catch()
Catch recovers from panics in the application and logs detailed error information. It captures the panic value, caller information, and stack trace for debugging. When debug mode is enabled, it logs the full stack trace; otherwise, it logs only the essential error details to avoid cluttering production logs.
This function should be called with defer at the beginning of main() and any goroutines:
func main() {
defer interruption.Catch()
// application logic
}
func OnSignal ¶
OnSignal registers a handler function to be called when the specified signals are received. It allows graceful shutdown or cleanup operations when the application receives termination signals. The returned context is canceled when the handler function returns, allowing the application to wait for cleanup operations to complete.
func SetupGracefulShutdown ¶
SetupGracefulShutdown is a convenience function that combines OnSignal and WaitForShutdown. It sets up signal handlers and returns a function that should be called with defer to wait for graceful shutdown. This is the recommended way to add graceful shutdown to your application.
Example usage:
func main() {
defer interruption.Handle()
defer interruption.SetupGracefulShutdown([]func() error{
func() error {
log.Info().Msg("database disconnecting...")
// database.Disconnect()
return nil
},
func() error {
log.Info().Msg("web server stopping...")
// web.Instance().Stop()
return nil
},
}, os.Interrupt, syscall.SIGTERM)
// Your application logic here
log.Info().Msg("application running...")
// Application will automatically wait for graceful shutdown when function exits
}
func WaitForShutdown ¶
WaitForShutdown waits for the provided context to be done, enabling graceful shutdown. This function is designed to be used with defer to ensure the application waits for signal handlers to complete before exiting.
Example usage:
func main() {
defer interruption.Handle()
ctx := interruption.OnSignal([]func() error{
func() error {
log.Info().Msg("shutting down gracefully...")
return nil
},
}, os.Interrupt, syscall.SIGTERM)
defer interruption.WaitForShutdown(ctx)
// Your application logic here
log.Info().Msg("application running...")
// Application will wait for signal and graceful shutdown when function exits
}
WaitForShutdown blocks until the provided context is cancelled, typically used to wait for graceful shutdown signal handlers to complete their cleanup operations. If the context is nil, the function returns immediately.
This function is commonly used in conjunction with OnSignal to implement graceful shutdown:
ctx := interruption.OnSignal(handlers, os.Interrupt, syscall.SIGTERM) defer interruption.WaitForShutdown(ctx)
Types ¶
This section is empty.
Source Files