destination reopening docs

docs/api.md

@@ -603,8 +603,12 @@ By default, `pino.destination` will use `process.stdout.fd` (1) as the file desc
 
 `pino.destination` is implemented on [`sonic-boom` ⇗]](https://github.com/mcollina/sonic-boom).
 
+A `pino.destination` instance can also be used to reopen closed files 
+(for example, for some log rotation scenarios), see [Reopening log files](/docs/help.md#reopening).
+
 * See [`destination` parameter](#destination)
-* See [`sonic-boom` ⇗](https://github.com/mcollina/sonic-boom).
+* See [`sonic-boom` ⇗](https://github.com/mcollina/sonic-boom)
+* See [Reopening log files](/docs/help.md#reopening)
 
 <a id="pino-extreme"></a>
 ### `pino.extreme([target]) => SonicBoom`
@@ -624,9 +628,13 @@ By default, `pino.destination` will use `process.stdout.fd` (1) as the file desc
 `pino.extreme` is implemented with the [`sonic-boom` ⇗](https://github.com/mcollina/sonic-boom)
 module.
 
+A `pino.extreme` instance can also be used to reopen closed files 
+(for example, for some log rotation scenarios), see [Reopening log files](/docs/help.md#reopening).
+
 * See [`destination` parameter](#destination)
 * See [`sonic-boom` ⇗](https://github.com/mcollina/sonic-boom)
 * See [Extreme mode ⇗](/docs/extreme.md)
+* See [Reopening log files](/docs/help.md#reopening)
 
 <a id="pino-final"></a>
 ### `pino.final(logger, handler) => Function`

docs/help.md

@@ -2,8 +2,9 @@
 
 * [Exit logging](#exit-logging)
 * [Log rotation](#rotate)
+* [Reopening log files](#reopening)
 * [Saving to multiple files](#multiple)
-* [Log Filtering](#filter-logs)
+* [Log filtering](#filter-logs)
 * [Transports and systemd](#transport-systemd)
 * [Duplicate keys](#dupe-keys)
 * [Log levels as labels instead of numbers](#level-string)
@@ -63,6 +64,25 @@ We would rotate our log files with logrotate, by adding the following to `/etc/l
 }
 ```
 
+<a id="reopening"></a>
+## Reopening log files
+
+In cases where a log rotation tool doesn't offer a copy-truncate capabilities, 
+or where using them is deemed inappropriate `pino.destination` and `pino.extreme`
+destinations are able to reopen file paths after a file has been moved away.
+
+One way to use this is to set up a SIGUSR2 or SIGHUP signal handler that 
+reopens the log file destination.
+
+```js
+const dest = pino.destination('/log/file') // pino.extreme will also work
+const logger = require('pino')(dest)
+process.on('SIGUSR2', () => dest.reopen())
+```
+
+The log rotation tool can then be configured to send this signal to the process 
+after a log rotation has occurred.
+
 <a id="multiple"></a>
 ## Saving to multiple files
 

docsify/sidebar.md

@@ -11,11 +11,12 @@
 * [Benchmarks](/docs/benchmarks.md)
 * [Legacy](/docs/legacy.md)
 * [Help](/docs/help.md)
-  * [Exit Logging](/docs/help.md#exit-logging)
-  * [Log Rotation](/docs/help.md#rotate)
-  * [Multiple Files](/docs/help.md#multiple)
-  * [Log Filtering](/docs/help.md#filter-logs)
-  * [Systemd](/docs/help.md#transport-systemd)
-  * [Duplicate Properties](/docs/help.md#dupe-keys)
-  * [Level Labels](/docs/help.md#level-string)
-  * [debug](/docs/help.md#debug)
+  * [Exit logging](/docs/help.md#exit-logging)
+  * [Log rotation](/docs/help.md#rotate)
+  * [Reopening log files](/docs/help.md#reopening)
+  * [Saving to multiple files](/docs/help.md#multiple)
+  * [Log filtering](/docs/help.md#filter-logs)
+  * [Transports and systemd](/docs/help.md#transport-systemd)
+  * [Duplicate keys](/docs/help.md#dupe-keys)
+  * [Log levels as labels instead of numbers](/docs/help.md#level-string)
+  * [Pino with `debug`](/docs/help.md#debug)