Improved documentation of Fatal Handlers
diff --git a/README.md b/README.md index ee8bd12..f8302c3 100644 --- a/README.md +++ b/README.md
@@ -384,3 +384,19 @@ hook.Reset() assert.Nil(hook.LastEntry()) ``` + +#### Fatal handlers + +Logrus can register one or more functions that will be called when any `fatal` +level message is logged. The registered handlers will be executed before +logrus performs a `os.Exit(1)`. This behavior may be helpful if callers need +to gracefully shutdown. Unlike a `panic("Something went wrong...")` call which can be intercepted with a deferred `recover` a call to `os.Exit(1)` can not be intercepted. + +``` +... +handler := func() { + // gracefully shutdown something... +} +logrus.RegisterExitHandler(handler) +... +```
diff --git a/alt_exit.go b/alt_exit.go index 889a504..b4c9e84 100644 --- a/alt_exit.go +++ b/alt_exit.go
@@ -51,9 +51,14 @@ os.Exit(code) } -// RegisterExitHandler adds a Logrus atexit handler, call logrus.Exit to invoke +// RegisterExitHandler adds a Logrus Exit handler, call logrus.Exit to invoke // all handlers. The handlers will also be invoked when any Fatal log entry is // made. +// +// This method is useful when a caller wishes to use logrus to log a fatal +// message but also needs to gracefully shutdown. An example usecase could be +// closing database connections, or sending a alert that the application is +// closing. func RegisterExitHandler(handler func()) { handlers = append(handlers, handler) }