@livy/restrain-handler

This Livy handler wraps another handler and buffers log records passed to it until an activation condition is reached.

The advantage of this approach is that you don't get any clutter in your log files. Only incidents which actually trigger an error (or whatever your activation condition is) will be in the logs, but they will contain all records, not only those above the level threshold.

Synchronous logger support: yes

Runtime: Node.js and browsers

Basic Example

const { RestrainHandler } = require('@livy/restrain-handler')
const { FileHandler } = require('@livy/file-handler')

const handler = new RestrainHandler(new FileHandler('logs.txt'), {
  activationStrategy: 'error'
})

Installation

Install it via npm:

npm install @livy/restrain-handler

Options

The first argument to this handler's constructor is a handler whose records to gate.

An object of options can be passed to the constructor as the second argument.

The following options are available:

activationStrategy

Type: LogLevel | (record: LogRecord) => boolean

Default: 'warning'

Description: Strategy which determines when this handler takes action. This can be a minimum log level to be reached by a log record, or a callback which receives each log record and returns true or false, indicating whether the handler should be activated.

bubble

Type: boolean

Default: true

Description: Controls whether records handled by this handler should bubble up to other handlers.

See also: Bubbling

bufferSize

Type: number

Default: Infinity

Description: Determines how many entries should be buffered at most. When the buffer exceeds this size, its oldest items are discarded.

stopBuffering

Type: boolean

Default: false

Description: Whether the handler should stop buffering after being triggered.

By default, when the handler is activated it will immediately start buffering again, only passing on new records when the activation condition is met again.

If this option is enabled, all log records that occur after an activation will be continuously passed on to the contained handler.

Public API

activate(mode)

Manually activate the handler and flush all buffered records. This respects the stopBuffering option.

A mode parameter needs to be passed to indicate whether the contained handler should be invoked synchronously ('sync') or asynchronously ('async').

bubble

Controls whether records handled by this handler should bubble up to other handlers. Initially set through the bubble option.

See also: Bubbling

close()

This handler implements the ClosableHandlerInterface. When closed (and the buffer is not empty), it also closes its wrapped handler (if applicable).

You usually don't want to call this method manually. It is done automatically when a Node.js process exits / a browser page is closed.

processors

This handler supports processors by implementing the ProcessableHandlerInterface.

reset()

This handler implements the ResettableInterface. Resetting it resets all attached processors and the wrapped handler (if applicable).

You usually don't want to call this method manually on an individual handler. Consider calling it on the logger instead.