diff --git a/doc/api/events.md b/doc/api/events.md index 0239e5abb5f28e..f3613d99100632 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -155,6 +155,18 @@ myEmitter.emit('error', new Error('whoops!')); // Prints: whoops! there was an error ``` +It is possible to monitor `'error'` events without consuming the emitted error +by installing a listener using the symbol `errorMonitor`. + +```js +const myEmitter = new MyEmitter(); +myEmitter.on(EventEmitter.errorMonitor, (err) => { + MyMonitoringTool.log(err); +}); +myEmitter.emit('error', new Error('whoops!')); +// Still throws and crashes Node.js +``` + ## Capture Rejections of Promises > Stability: 1 - captureRejections is experimental. @@ -348,6 +360,19 @@ the event emitter instance, the event’s name and the number of attached listeners, respectively. Its `name` property is set to `'MaxListenersExceededWarning'`. +### `EventEmitter.errorMonitor` + + +This symbol shall be used to install a listener for only monitoring `'error'` +events. Listeners installed using this symbol are called before the regular +`'error'` listeners are called. + +Installing a listener using this symbol does not change the behavior once an +`'error'` event is emitted, therefore the process will still crash if no +regular `'error'` listener is installed. + ### `emitter.addListener(eventName, listener)`