103 lines
3.3 KiB
Markdown
103 lines
3.3 KiB
Markdown
# Asynchronous Logging
|
|
|
|
In essence, asynchronous logging enables even faster performance by Pino.
|
|
|
|
In Pino's standard mode of operation log messages are directly written to the
|
|
output stream as the messages are generated with a _blocking_ operation.
|
|
Asynchronous logging works by buffering
|
|
log messages and writing them in larger chunks.
|
|
|
|
```js
|
|
const pino = require('pino')
|
|
const logger = pino(pino.destination({
|
|
dest: './my-file', // omit for stdout
|
|
minLength: 4096, // Buffer before writing
|
|
sync: false // Asynchronous logging
|
|
}))
|
|
```
|
|
|
|
* See [`pino.destination`](/docs/api.md#pino-destination)
|
|
* `pino.destination` is implemented on [`sonic-boom` ⇗](https://github.com/mcollina/sonic-boom).
|
|
|
|
### AWS Lambda
|
|
|
|
On AWS Lambda we recommend to call `dest.flushSync()` at the end
|
|
of each function execution to avoid losing data.
|
|
|
|
## Usage
|
|
|
|
The `pino.destination({ sync: false })` method will provide an asynchronous destination.
|
|
|
|
```js
|
|
const pino = require('pino')
|
|
const dest = pino.destination({ sync: false }) // logs to stdout with no args
|
|
const logger = pino(dest)
|
|
```
|
|
|
|
<a id='log-loss-prevention'></a>
|
|
## Prevent log loss in Node v12
|
|
|
|
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')
|
|
const dest = pino.destination({ sync: false })
|
|
const logger = pino(dest)
|
|
|
|
// asynchronously flush every 10 seconds to keep the buffer empty
|
|
// in periods of low activity
|
|
setInterval(function () {
|
|
logger.flush()
|
|
}, 10000).unref()
|
|
|
|
// use pino.final to create a special logger that
|
|
// guarantees final tick writes
|
|
const handler = pino.final(logger, (err, finalLogger, evt) => {
|
|
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('SIGINT', () => handler(null, 'SIGINT'))
|
|
process.on('SIGQUIT', () => handler(null, 'SIGQUIT'))
|
|
process.on('SIGTERM', () => handler(null, 'SIGTERM'))
|
|
```
|
|
|
|
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
|
|
|
|
Asynchronous logging has a couple of important caveats:
|
|
|
|
* 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
|
|
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)
|