Bring the asynchronous logging doc up to v7 (#1171)

docs/api.md

@@ -347,7 +347,7 @@ and searching for logged objects can start from a consistent path.
 
 Default: `false`
 
-__DEPRECATED: use [`transport`](#transport) instead.
+__DEPRECATED: use [`transport`](#transport) instead.__
 
 Enables pretty printing log logs. This is intended for non-production
 configurations. This may be set to a configuration object as outlined in the
@@ -1033,8 +1033,12 @@ For more on transports, how they work, and how to create them see the [`Transpor
 
 ### `pino.final(logger, [handler]) => Function | FinalLogger`
 
+__The use of `pino.final` is discouraged in Node.js v14+ and not required.
+It will be removed in the next major version.__
+
 The `pino.final` method can be used to acquire a final logger instance
-or create an exit listener function.
+or create an exit listener function. This is _not_ needed in Node.js v14+
+as pino automatically can handle those.
 
 The `finalLogger` is a specialist logger that synchronously flushes
 on every write. This is important to guarantee final log writes,

docs/asynchronous.md

@@ -35,9 +35,11 @@ const logger = pino(dest)
 ```
 
 <a id='log-loss-prevention'></a>
-## Log loss prevention
+## Prevent log loss in Node v12
 
-The following strategy can be used to minimize log loss:
+In Node.js v14+, streams created by `pino.destination()` are automatically 
+flushed whenever the process exits.
+In Node v12, `pino.final()` can be used to prevent log loss. Here is an example:
 
 ```js
 const pino = require('pino')
@@ -66,45 +68,35 @@ process.on('SIGQUIT', () => handler(null, 'SIGQUIT'))
 process.on('SIGTERM', () => handler(null, 'SIGTERM'))
 ```
 
-Note that the use of `pino.final` is not strictly required when using Node v14+.
+The above code will register handlers for the following process events/signals so that
+pino can flush the asynchronous logger buffer:
+
++ `beforeExit`
++ `exit`
++ `uncaughtException`
++ `SIGINT`
++ `SIGQUIT`
++ `SIGTERM`
+
+In all of these cases, except `SIGHUP`, the process is in a state that it
+*must* terminate. Note that the handler has a `process.exit(1)` at the end.
+
+
+* See also [`pino.final` api](/docs/api.md#pino-final)
 
 ## Caveats
 
-This has a couple of important caveats:
+Asynchronous logging has a couple of important caveats:
 
-* 4KB of spare RAM will be needed for logging
 * As opposed to the default mode, there is not a one-to-one relationship between
   calls to logging methods (e.g. `logger.info`) and writes to a log file
 * There is a possibility of the most recently buffered log messages being lost
-  (up to 4KB of logs)
-  * For instance, a power cut will mean up to 4KB of buffered logs will be lost
-
-So in summary, use asynchronous logging only when performing an extreme amount of
-logging, and it is acceptable to potentially lose the most recent logs.
-
-* Pino will register handlers for the following process events/signals so that
-  Pino can flush the asynchronous logger buffer:
-
-  + `beforeExit`
-  + `exit`
-  + `uncaughtException`
-  + `SIGHUP`
-  + `SIGINT`
-  + `SIGQUIT`
-  + `SIGTERM`
-
-  In all of these cases, except `SIGHUP`, the process is in a state that it
-  *must* terminate. Thus, if an `onTerminated` function isn't registered when
-  constructing a Pino instance (see [pino#constructor](api.md#constructor)),
-  then Pino will invoke `process.exit(0)` when no error has occurred, or
-  `process.exit(1)` otherwise. If an `onTerminated` function is supplied, it
-  is the responsibility of the `onTerminated` function to manually exit the process.
-
-  In the case of `SIGHUP`, we will look to see if any other handlers are
-  registered for the event. If not, we will proceed as we do with all other
-  signals. If there are more handlers registered than just our own, we will
-  simply flush the asynchronous logging buffer.
-
-* See [`pino.destination` api](/docs/api.md#pino-destination)
-* See [`pino.final` api](/docs/api.md#pino-final)
-* See [`destination` parameter](/docs/api.md#destination)
+  in case of a system failure, e.g. a power cut.
+* In Node v14+, Pino will register handlers for the `exit` and `beforeExit` handler so that
+  the stream is flushed automatically. This is implemented with the usage of
+  [`on-exit-leak-free`](https://github.com/mcollina/on-exit-leak-free).
+
+See also:
+
+* [`pino.destination` api](/docs/api.md#pino-destination)
+* [`destination` parameter](/docs/api.md#destination)