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)
}
