doc improvements per review

docs/api.md

@@ -636,20 +636,29 @@ supplied to process exit events such as `exit`, `uncaughtException`,
 `SIGHUP` and so on. 
 
 The exit listener function will call the supplied `handler` function 
-with a `finalLogger` instance. The `finalLogger` is a specialist 
-logger that synchronously flushes on every write. This is important 
-to gaurantee final log writes, both when using `pino.destination` or
-`pino.extreme` targets. 
+with an error object (or else `null`), a `finalLogger` instance followed
+by any additional arguments the `handler` may be called with. 
+The `finalLogger` is a specialist logger that synchronously flushes 
+on every write. This is important to gaurantee final log writes, 
+both when using `pino.destination` or `pino.extreme` targets. 
 
 Since final log writes cannot be gauranteed with normal Node.js streams, 
 if the `destination` parameter of the `logger` supplied to `pino.final`
 is a Node.js stream `pino.final` will throw. It's highly recommended
 for both performance and safety to use `pino.destination`/`pino.extreme`
 destinations.
 
+```js
+process.on('uncaughtException', pino.final(logger, (err, finalLogger) => {
+  finalLogger.error(err, 'uncaughtException')
+  process.exit(1)
+}))
+```
+
 * See [`destination` parameter](#destination)
 * See [Exit logging help](/docs/help.md#exit-logging)
 * See [Extreme mode ⇗](/docs/extreme.md)
+* See [Log loss prevention ⇗](/docs/extreme.md#log-loss-prevention)
 
 <a id="pino-stdserializers"></a>
 ### `pino.stdSerializers` (Object)

docs/extreme.md

@@ -53,6 +53,7 @@ const dest = pino.extreme() // logs to stdout with no args
 const logger = pino(dest)
 ```
 
+<a id='log-loss-prevention'></a>
 ## Log loss prevention
 
 The following strategy can be used to minimize log loss:
@@ -62,7 +63,7 @@ const pino = require('pino')
 const dest = pino.extreme() // no arguments
 const logger = pino(dest)
 
-// flush every 10 seconds to keep the buffer empty 
+// asynchronously flush every 10 seconds to keep the buffer empty 
 // in periods of low activity
 setInterval(function () {
   logger.flush()
@@ -71,14 +72,14 @@ setInterval(function () {
 // use pino.final to create a special logger that 
 // guarantees final tick writes 
 const handler = pino.final(logger, (err, finalLogger, evt) => {
-  if (err) finalLogger.error(err, 'error caused exit')
   finalLogger.info(`${evt} caught`)
+  if (err) finalLogger.error(err, 'error caused exit')
+  process.exit(err ? 1 : 0)
 })
 // catch all the ways node might exit
 process.on('beforeExit', () => handler(null, 'beforeExit'))
 process.on('exit', () => handler(null, 'exit'))
 process.on('uncaughtException', (err) => handler(err, 'uncaughtException'))
-process.on('SIGHUP', () => handler(null, 'SIGHUP'))
 process.on('SIGINT', () => handler(null, 'SIGINT'))
 process.on('SIGQUIT', () => handler(null, 'SIGQUIT'))
 process.on('SIGTERM', () => handler(null, 'SIGTERM'))

docs/help.md

@@ -19,11 +19,17 @@ in cases of error.
 Writing to a Node.js stream on exit is not necessarily guaranteed, and naively writing
 to an Extreme Mode logger on exit will definitely lead to lost logs. 
 
-To write logs in an exit handler, create the handler with `pino.final`:
+To write logs in an exit handler, create the handler with [`pino.final`](/docs/api.md#pino-final):
 
 ```js
 process.on('uncaughtException', pino.final(logger, (err, finalLogger) => {
-  finalLogger.error(err)
+  finalLogger.error(err, 'uncaughtException')
+  process.exit(1)
+}))
+
+process.on('unhandledRejection', pino.final(logger, (err, finalLogger) => {
+  finalLogger.error(err, 'unhandledRejection')
+  process.exit(1)
 }))
 ```