shell-mirror 1.5.23 → 1.5.25

package/mac-agent/node_modules/winston/README.md

@@ -0,0 +1,1271 @@
+# winston
+
+A logger for just about everything.
+
+[![Version npm](https://img.shields.io/npm/v/winston.svg?style=flat-square)](https://www.npmjs.com/package/winston)
+[![npm Downloads](https://img.shields.io/npm/dm/winston.svg?style=flat-square)](https://npmcharts.com/compare/winston?minimal=true)
+[![build status](https://github.com/winstonjs/winston/actions/workflows/ci.yml/badge.svg)](https://github.com/winstonjs/winston/actions/workflows/ci.yml)
+[![coverage status](https://coveralls.io/repos/github/winstonjs/winston/badge.svg?branch=master)](https://coveralls.io/github/winstonjs/winston?branch=master)
+
+[![NPM](https://nodei.co/npm/winston.png?downloads=true&downloadRank=true)](https://nodei.co/npm/winston/)
+
+## winston@3
+
+See the [Upgrade Guide](UPGRADE-3.0.md) for more information. Bug reports and
+PRs welcome!
+
+## Looking for `winston@2.x` documentation?
+
+Please note that the documentation below is for `winston@3`.
+[Read the `winston@2.x` documentation].
+
+## Motivation
+
+`winston` is designed to be a simple and universal logging library with
+support for multiple transports. A transport is essentially a storage device
+for your logs. Each `winston` logger can have multiple transports (see:
+[Transports]) configured at different levels (see: [Logging levels]). For
+example, one may want error logs to be stored in a persistent remote location
+(like a database), but all logs output to the console or a local file.
+
+`winston` aims to decouple parts of the logging process to make it more
+flexible and extensible. Attention is given to supporting flexibility in log
+formatting (see: [Formats]) & levels (see: [Using custom logging levels]), and
+ensuring those APIs decoupled from the implementation of transport logging
+(i.e. how the logs are stored / indexed, see: [Adding Custom Transports]) to
+the API that they exposed to the programmer.
+
+## Quick Start
+
+TL;DR? Check out the [quick start example][quick-example] in `./examples/`.
+There are a number of other examples in [`./examples/*.js`][examples].
+Don't see an example you think should be there? Submit a pull request
+to add it!
+
+## Usage
+
+The recommended way to use `winston` is to create your own logger. The
+simplest way to do this is using `winston.createLogger`:
+
+``` js
+const winston = require('winston');
+
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  defaultMeta: { service: 'user-service' },
+  transports: [
+    //
+    // - Write all logs with importance level of `error` or higher to `error.log`
+    //   (i.e., error, fatal, but not other levels)
+    //
+    new winston.transports.File({ filename: 'error.log', level: 'error' }),
+    //
+    // - Write all logs with importance level of `info` or higher to `combined.log`
+    //   (i.e., fatal, error, warn, and info, but not trace)
+    //
+    new winston.transports.File({ filename: 'combined.log' }),
+  ],
+});
+
+//
+// If we're not in production then log to the `console` with the format:
+// `${info.level}: ${info.message} JSON.stringify({ ...rest }) `
+//
+if (process.env.NODE_ENV !== 'production') {
+  logger.add(new winston.transports.Console({
+    format: winston.format.simple(),
+  }));
+}
+```
+
+You may also log directly via the default logger exposed by
+`require('winston')`, but this merely intended to be a convenient shared
+logger to use throughout your application if you so choose.
+Note that the default logger doesn't have any transports by default.
+You need add transports by yourself, and leaving the default logger without any
+transports may produce a high memory usage issue.
+
+## Table of contents
+
+* [Motivation](#motivation)
+* [Quick Start](#quick-start)
+* [Usage](#usage)
+* [Table of Contents](#table-of-contents)
+* [Logging](#logging)
+  * [Creating your logger](#creating-your-own-logger)
+  * [Streams, `objectMode`, and `info` objects](#streams-objectmode-and-info-objects)
+* [Formats]
+  * [Combining formats](#combining-formats)
+  * [String interpolation](#string-interpolation)
+  * [Filtering `info` Objects](#filtering-info-objects)
+  * [Creating custom formats](#creating-custom-formats)
+* [Logging levels]
+  * [Using logging levels](#using-logging-levels)
+  * [Using custom logging levels](#using-custom-logging-levels)
+* [Transports]
+  * [Multiple transports of the same type](#multiple-transports-of-the-same-type)
+  * [Adding Custom Transports](#adding-custom-transports)
+  * [Common Transport options](#common-transport-options)
+* [Exceptions](#exceptions)
+  * [Handling Uncaught Exceptions with winston](#handling-uncaught-exceptions-with-winston)
+  * [To Exit or Not to Exit](#to-exit-or-not-to-exit)
+* [Rejections](#rejections)
+  * [Handling Uncaught Promise Rejections with winston](#handling-uncaught-promise-rejections-with-winston)
+* [Profiling](#profiling)
+* [Streaming Logs](#streaming-logs)
+* [Querying Logs](#querying-logs)
+* [Further Reading](#further-reading)
+  * [Using the default logger](#using-the-default-logger)
+  * [Awaiting logs to be written in `winston`](#awaiting-logs-to-be-written-in-winston)
+  * [Working with multiple Loggers in `winston`](#working-with-multiple-loggers-in-winston)
+  * [Routing Console transport messages to the console instead of stdout and stderr](#routing-console-transport-messages-to-the-console-instead-of-stdout-and-stderr)
+* [Installation](#installation)
+* [Run Tests](#run-tests)
+
+## Logging
+
+Logging levels in `winston` conform to the severity ordering specified by
+[RFC5424]: _severity of all levels is assumed to be numerically **ascending**
+from most important to least important._
+
+``` js
+const levels = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  verbose: 4,
+  debug: 5,
+  silly: 6
+};
+```
+
+### Creating your own Logger
+You get started by creating a logger using `winston.createLogger`:
+
+``` js
+const logger = winston.createLogger({
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+```
+
+A logger accepts the following parameters:
+
+| Name          | Default                     |  Description    |
+| ------------- | --------------------------- | --------------- |
+| `level`       | `'info'`                    | Log only if [`info.level`](#streams-objectmode-and-info-objects) is less than or equal to this level  |
+| `levels`      | `winston.config.npm.levels` | Levels (and colors) representing log priorities            |
+| `format`      | `winston.format.json`       | Formatting for `info` messages  (see: [Formats])           |
+| `transports`  | `[]` _(No transports)_      | Set of logging targets for `info` messages                 |
+| `exitOnError` | `true`                      | If false, handled exceptions will not cause `process.exit` |
+| `silent`      | `false`                     | If true, all logs are suppressed |
+
+The levels provided to `createLogger` will be defined as convenience methods
+on the `logger` returned.
+
+``` js
+//
+// Logging
+//
+logger.log({
+  level: 'info',
+  message: 'Hello distributed log files!'
+});
+
+logger.info('Hello again distributed logs');
+```
+
+You can add or remove transports from the `logger` once it has been provided
+to you from `winston.createLogger`:
+
+``` js
+const files = new winston.transports.File({ filename: 'combined.log' });
+const console = new winston.transports.Console();
+
+logger
+  .clear()          // Remove all transports
+  .add(console)     // Add console transport
+  .add(files)       // Add file transport
+  .remove(console); // Remove console transport
+```
+
+You can also wholesale reconfigure a `winston.Logger` instance using the
+`configure` method:
+
+``` js
+const logger = winston.createLogger({
+  level: 'info',
+  transports: [
+    new winston.transports.Console(),
+    new winston.transports.File({ filename: 'combined.log' })
+  ]
+});
+
+//
+// Replaces the previous transports with those in the
+// new configuration wholesale.
+//
+const DailyRotateFile = require('winston-daily-rotate-file');
+logger.configure({
+  level: 'verbose',
+  transports: [
+    new DailyRotateFile(opts)
+  ]
+});
+```
+
+### Creating child loggers
+
+You can create child loggers from existing loggers to pass metadata overrides:
+
+``` js
+const logger = winston.createLogger({
+  transports: [
+    new winston.transports.Console(),
+  ]
+});
+
+const childLogger = logger.child({ requestId: '451' });
+```
+> `.child` is likely to be bugged if you're also extending the `Logger` class, due to some implementation details that make `this` keyword to point to unexpected things. Use with caution.
+
+### Streams, `objectMode`, and `info` objects
+
+In `winston`, both `Logger` and `Transport` instances are treated as
+[`objectMode`](https://nodejs.org/api/stream.html#stream_object_mode)
+streams that accept an `info` object.
+
+The `info` parameter provided to a given format represents a single log
+message. The object itself is mutable. Every `info` must have at least the
+`level` and `message` properties:
+
+``` js
+const info = {
+  level: 'info',                 // Level of the logging message
+  message: 'Hey! Log something?' // Descriptive message being logged.
+};
+```
+
+Properties **besides level and message** are considered as "`meta`". i.e.:
+
+``` js
+const { level, message, ...meta } = info;
+```
+
+Several of the formats in `logform` itself add additional properties:
+
+| Property    | Format added by | Description |
+| ----------- | --------------- | ----------- |
+| `splat`     | `splat()`       | String interpolation splat for `%d %s`-style messages. |
+| `timestamp` | `timestamp()`   |  timestamp the message was received. |
+| `label`     | `label()`       | Custom label associated with each message. |
+| `ms`        | `ms()`          | Number of milliseconds since the previous log message. |
+
+As a consumer you may add whatever properties you wish – _internal state is
+maintained by `Symbol` properties:_
+
+- `Symbol.for('level')` _**(READ-ONLY)**:_ equal to `level` property.
+  **Is treated as immutable by all code.**
+- `Symbol.for('message'):` complete string message set by "finalizing formats":
+  - `json`
+  - `logstash`
+  - `printf`
+  - `prettyPrint`
+  - `simple`
+- `Symbol.for('splat')`: additional string interpolation arguments. _Used
+  exclusively by `splat()` format._
+
+These Symbols are stored in another package: `triple-beam` so that all
+consumers of `logform` can have the same Symbol reference. i.e.:
+
+``` js
+const { LEVEL, MESSAGE, SPLAT } = require('triple-beam');
+
+console.log(LEVEL === Symbol.for('level'));
+// true
+
+console.log(MESSAGE === Symbol.for('message'));
+// true
+
+console.log(SPLAT === Symbol.for('splat'));
+// true
+```
+
+> **NOTE:** any `{ message }` property in a `meta` object provided will
+> automatically be concatenated to any `msg` already provided: For
+> example the below will concatenate 'world' onto 'hello':
+>
+> ``` js
+> logger.log('error', 'hello', { message: 'world' });
+> logger.info('hello', { message: 'world' });
+> ```
+
+## Formats
+
+Formats in `winston` can be accessed from `winston.format`. They are
+implemented in [`logform`](https://github.com/winstonjs/logform), a separate
+module from `winston`. This allows flexibility when writing your own transports
+in case you wish to include a default format with your transport.
+
+In modern versions of `node` template strings are very performant and are the
+recommended way for doing most end-user formatting. If you want to bespoke
+format your logs, `winston.format.printf` is for you:
+
+``` js
+const { createLogger, format, transports } = require('winston');
+const { combine, timestamp, label, printf } = format;
+
+const myFormat = printf(({ level, message, label, timestamp }) => {
+  return `${timestamp} [${label}] ${level}: ${message}`;
+});
+
+const logger = createLogger({
+  format: combine(
+    label({ label: 'right meow!' }),
+    timestamp(),
+    myFormat
+  ),
+  transports: [new transports.Console()]
+});
+```
+
+To see what built-in formats are available and learn more about creating your
+own custom logging formats, see [`logform`][logform].
+
+### Combining formats
+
+Any number of formats may be combined into a single format using
+`format.combine`. Since `format.combine` takes no `opts`, as a convenience it
+returns pre-created instance of the combined format.
+
+``` js
+const { createLogger, format, transports } = require('winston');
+const { combine, timestamp, label, prettyPrint } = format;
+
+const logger = createLogger({
+  format: combine(
+    label({ label: 'right meow!' }),
+    timestamp(),
+    prettyPrint()
+  ),
+  transports: [new transports.Console()]
+})
+
+logger.log({
+  level: 'info',
+  message: 'What time is the testing at?'
+});
+// Outputs:
+// { level: 'info',
+//   message: 'What time is the testing at?',
+//   label: 'right meow!',
+//   timestamp: '2017-09-30T03:57:26.875Z' }
+```
+
+### String interpolation
+
+The `log` method provides the string interpolation using [util.format]. **It
+must be enabled using `format.splat()`.**
+
+Below is an example that defines a format with string interpolation of
+messages using `format.splat` and then serializes the entire `info` message
+using `format.simple`.
+
+``` js
+const { createLogger, format, transports } = require('winston');
+const logger = createLogger({
+  format: format.combine(
+    format.splat(),
+    format.simple()
+  ),
+  transports: [new transports.Console()]
+});
+
+// info: test message my string {}
+logger.log('info', 'test message %s', 'my string');
+
+// info: test message 123 {}
+logger.log('info', 'test message %d', 123);
+
+// info: test message first second {number: 123}
+logger.log('info', 'test message %s, %s', 'first', 'second', { number: 123 });
+```
+
+### Filtering `info` Objects
+
+If you wish to filter out a given `info` Object completely when logging then
+simply return a falsey value.
+
+``` js
+const { createLogger, format, transports } = require('winston');
+
+// Ignore log messages if they have { private: true }
+const ignorePrivate = format((info, opts) => {
+  if (info.private) { return false; }
+  return info;
+});
+
+const logger = createLogger({
+  format: format.combine(
+    ignorePrivate(),
+    format.json()
+  ),
+  transports: [new transports.Console()]
+});
+
+// Outputs: {"level":"error","message":"Public error to share"}
+logger.log({
+  level: 'error',
+  message: 'Public error to share'
+});
+
+// Messages with { private: true } will not be written when logged.
+logger.log({
+  private: true,
+  level: 'error',
+  message: 'This is super secret - hide it.'
+});
+```
+
+Use of `format.combine` will respect any falsey values return and stop
+evaluation of later formats in the series. For example:
+
+``` js
+const { format } = require('winston');
+const { combine, timestamp, label } = format;
+
+const willNeverThrow = format.combine(
+  format(info => { return false })(), // Ignores everything
+  format(info => { throw new Error('Never reached') })()
+);
+```
+
+### Creating custom formats
+
+Formats are prototypal objects (i.e. class instances) that define a single
+method: `transform(info, opts)` and return the mutated `info`:
+
+- `info`: an object representing the log message.
+- `opts`: setting specific to the current instance of the format.
+
+They are expected to return one of two things:
+
+- **An `info` Object** representing the modified `info` argument. Object
+references need not be preserved if immutability is preferred. All current
+built-in formats consider `info` mutable, but [immutablejs] is being
+considered for future releases.
+- **A falsey value** indicating that the `info` argument should be ignored by the
+caller. (See: [Filtering `info` Objects](#filtering-info-objects)) below.
+
+`winston.format` is designed to be as simple as possible. To define a new
+format, simply pass it a `transform(info, opts)` function to get a new
+`Format`.
+
+The named `Format` returned can be used to create as many copies of the given
+`Format` as desired:
+
+``` js
+const { format } = require('winston');
+
+const volume = format((info, opts) => {
+  if (opts.yell) {
+    info.message = info.message.toUpperCase();
+  } else if (opts.whisper) {
+    info.message = info.message.toLowerCase();
+  }
+
+  return info;
+});
+
+// `volume` is now a function that returns instances of the format.
+const scream = volume({ yell: true });
+console.dir(scream.transform({
+  level: 'info',
+  message: `sorry for making you YELL in your head!`
+}, scream.options));
+// {
+//   level: 'info'
+//   message: 'SORRY FOR MAKING YOU YELL IN YOUR HEAD!'
+// }
+
+// `volume` can be used multiple times to create different formats.
+const whisper = volume({ whisper: true });
+console.dir(whisper.transform({
+  level: 'info',
+  message: `WHY ARE THEY MAKING US YELL SO MUCH!`
+}, whisper.options));
+// {
+//   level: 'info'
+//   message: 'why are they making us yell so much!'
+// }
+```
+
+## Logging Levels
+
+Logging levels in `winston` conform to the severity ordering specified by
+[RFC5424]: _severity of all levels is assumed to be numerically **ascending**
+from most important to least important._
+
+Each `level` is given a specific integer priority. The higher the priority the
+more important the message is considered to be, and the lower the
+corresponding integer priority.  For example, as specified exactly in RFC5424
+the `syslog` levels are prioritized from 0 to 7 (highest to lowest).
+
+```js
+{
+  emerg: 0,
+  alert: 1,
+  crit: 2,
+  error: 3,
+  warning: 4,
+  notice: 5,
+  info: 6,
+  debug: 7
+}
+```
+
+Similarly, `npm` logging levels are prioritized from 0 to 6 (highest to
+lowest):
+
+``` js
+{
+  error: 0,
+  warn: 1,
+  info: 2,
+  http: 3,
+  verbose: 4,
+  debug: 5,
+  silly: 6
+}
+```
+
+If you do not explicitly define the levels that `winston` should use, the
+`npm` levels above will be used.
+
+### Using Logging Levels
+
+Setting the level for your logging message can be accomplished in one of two
+ways. You can pass a string representing the logging level to the log() method
+or use the level specified methods defined on every winston Logger.
+
+``` js
+//
+// Any logger instance
+//
+logger.log('silly', "127.0.0.1 - there's no place like home");
+logger.log('debug', "127.0.0.1 - there's no place like home");
+logger.log('verbose', "127.0.0.1 - there's no place like home");
+logger.log('info', "127.0.0.1 - there's no place like home");
+logger.log('warn', "127.0.0.1 - there's no place like home");
+logger.log('error', "127.0.0.1 - there's no place like home");
+logger.info("127.0.0.1 - there's no place like home");
+logger.warn("127.0.0.1 - there's no place like home");
+logger.error("127.0.0.1 - there's no place like home");
+
+//
+// Default logger
+//
+winston.log('info', "127.0.0.1 - there's no place like home");
+winston.info("127.0.0.1 - there's no place like home");
+```
+
+`winston` allows you to define a `level` property on each transport which
+specifies the **maximum** level of messages that a transport should log. For
+example, using the `syslog` levels you could log only `error` messages to the
+console and everything `info` and below to a file (which includes `error`
+messages):
+
+``` js
+const logger = winston.createLogger({
+  levels: winston.config.syslog.levels,
+  transports: [
+    new winston.transports.Console({ level: 'error' }),
+    new winston.transports.File({
+      filename: 'combined.log',
+      level: 'info'
+    })
+  ]
+});
+```
+
+You may also dynamically change the log level of a transport:
+
+``` js
+const transports = {
+  console: new winston.transports.Console({ level: 'warn' }),
+  file: new winston.transports.File({ filename: 'combined.log', level: 'error' })
+};
+
+const logger = winston.createLogger({
+  transports: [
+    transports.console,
+    transports.file
+  ]
+});
+
+logger.info('Will not be logged in either transport!');
+transports.console.level = 'info';
+transports.file.level = 'info';
+logger.info('Will be logged in both transports!');
+```
+
+`winston` supports customizable logging levels, defaulting to npm style
+logging levels. Levels must be specified at the time of creating your logger.
+
+### Using Custom Logging Levels
+
+In addition to the predefined `npm`, `syslog`, and `cli` levels available in
+`winston`, you can also choose to define your own:
+
+``` js
+const myCustomLevels = {
+  levels: {
+    foo: 0,
+    bar: 1,
+    baz: 2,
+    foobar: 3
+  },
+  colors: {
+    foo: 'blue',
+    bar: 'green',
+    baz: 'yellow',
+    foobar: 'red'
+  }
+};
+
+const customLevelLogger = winston.createLogger({
+  levels: myCustomLevels.levels
+});
+
+customLevelLogger.foobar('some foobar level-ed message');
+```
+
+Although there is slight repetition in this data structure, it enables simple
+encapsulation if you do not want to have colors. If you do wish to have
+colors, in addition to passing the levels to the Logger itself, you must make
+winston aware of them:
+
+``` js
+winston.addColors(myCustomLevels.colors);
+```
+
+This enables loggers using the `colorize` formatter to appropriately color and style
+the output of custom levels.
+
+Additionally, you can also change background color and font style.
+For example,
+``` js
+baz: 'italic yellow',
+foobar: 'bold red cyanBG'
+```
+
+Possible options are below.
+
+* Font styles: `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`,
+  `strikethrough`.
+
+* Font foreground colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`,
+  `cyan`, `white`, `gray`, `grey`.
+
+* Background colors: `blackBG`, `redBG`, `greenBG`, `yellowBG`, `blueBG`
+  `magentaBG`, `cyanBG`, `whiteBG`
+
+### Colorizing Standard logging levels
+
+To colorize the standard logging level add
+```js
+winston.format.combine(
+  winston.format.colorize(),
+  winston.format.simple()
+);
+```
+where `winston.format.simple()` is whatever other formatter you want to use.  The `colorize` formatter must come before any formatters adding text you wish to color.
+
+### Colorizing full log line when json formatting logs
+
+To colorize the full log line with the json formatter you can apply the following
+
+```js
+winston.format.combine(
+  winston.format.json(),
+  winston.format.colorize({ all: true })
+);
+```
+
+## Transports
+
+There are several [core transports] included in  `winston`, which leverage the
+built-in networking and file I/O offered by Node.js core. In addition, there
+are [additional transports] written by members of the community.
+
+## Multiple transports of the same type
+
+It is possible to use multiple transports of the same type e.g.
+`winston.transports.File` when you construct the transport.
+
+``` js
+const logger = winston.createLogger({
+  transports: [
+    new winston.transports.File({
+      filename: 'combined.log',
+      level: 'info'
+    }),
+    new winston.transports.File({
+      filename: 'errors.log',
+      level: 'error'
+    })
+  ]
+});
+```
+
+If you later want to remove one of these transports you can do so by using the
+transport itself. e.g.:
+
+``` js
+const combinedLogs = logger.transports.find(transport => {
+  return transport.filename === 'combined.log'
+});
+
+logger.remove(combinedLogs);
+```
+
+## Adding Custom Transports
+
+Adding a custom transport is easy. All you need to do is accept any options
+you need, implement a log() method, and consume it with `winston`.
+
+``` js
+const Transport = require('winston-transport');
+const util = require('util');
+
+//
+// Inherit from `winston-transport` so you can take advantage
+// of the base functionality and `.exceptions.handle()`.
+//
+module.exports = class YourCustomTransport extends Transport {
+  constructor(opts) {
+    super(opts);
+    //
+    // Consume any custom options here. e.g.:
+    // - Connection information for databases
+    // - Authentication information for APIs (e.g. loggly, papertrail,
+    //   logentries, etc.).
+    //
+  }
+
+  log(info, callback) {
+    setImmediate(() => {
+      this.emit('logged', info);
+    });
+
+    // Perform the writing to the remote service
+    callback();
+  }
+};
+```
+
+## Common Transport options
+
+As every transport inherits from [winston-transport], it's possible to set
+a custom format and a custom log level on each transport separately:
+
+``` js
+const logger = winston.createLogger({
+  transports: [
+    new winston.transports.File({
+      filename: 'error.log',
+      level: 'error',
+      format: winston.format.json()
+    }),
+    new winston.transports.Http({
+      level: 'warn',
+      format: winston.format.json()
+    }),
+    new winston.transports.Console({
+      level: 'info',
+      format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.simple()
+      )
+    })
+  ]
+});
+```
+
+## Exceptions
+
+### Handling Uncaught Exceptions with winston
+
+With `winston`, it is possible to catch and log `uncaughtException` events
+from your process. With your own logger instance you can enable this behavior
+when it's created or later on in your applications lifecycle:
+
+``` js
+const { createLogger, transports } = require('winston');
+
+// Enable exception handling when you create your logger.
+const logger = createLogger({
+  transports: [
+    new transports.File({ filename: 'combined.log' })
+  ],
+  exceptionHandlers: [
+    new transports.File({ filename: 'exceptions.log' })
+  ]
+});
+
+// Or enable it later on by adding a transport or using `.exceptions.handle`
+const logger = createLogger({
+  transports: [
+    new transports.File({ filename: 'combined.log' })
+  ]
+});
+
+// Call exceptions.handle with a transport to handle exceptions
+logger.exceptions.handle(
+  new transports.File({ filename: 'exceptions.log' })
+);
+```
+
+If you want to use this feature with the default logger, simply call
+`.exceptions.handle()` with a transport instance.
+
+``` js
+//
+// You can add a separate exception logger by passing it to `.exceptions.handle`
+//
+winston.exceptions.handle(
+  new winston.transports.File({ filename: 'path/to/exceptions.log' })
+);
+
+//
+// Alternatively you can set `handleExceptions` to true when adding transports
+// to winston.
+//
+winston.add(new winston.transports.File({
+  filename: 'path/to/combined.log',
+  handleExceptions: true
+}));
+```
+
+### To Exit or Not to Exit
+
+By default, winston will exit after logging an uncaughtException. If this is
+not the behavior you want, set `exitOnError = false`
+
+``` js
+const logger = winston.createLogger({ exitOnError: false });
+
+//
+// or, like this:
+//
+logger.exitOnError = false;
+```
+
+When working with custom logger instances, you can pass in separate transports
+to the `exceptionHandlers` property or set `handleExceptions` on any
+transport.
+
+##### Example 1
+
+``` js
+const logger = winston.createLogger({
+  transports: [
+    new winston.transports.File({ filename: 'path/to/combined.log' })
+  ],
+  exceptionHandlers: [
+    new winston.transports.File({ filename: 'path/to/exceptions.log' })
+  ]
+});
+```
+
+##### Example 2
+
+``` js
+const logger = winston.createLogger({
+  transports: [
+    new winston.transports.Console({
+      handleExceptions: true
+    })
+  ],
+  exitOnError: false
+});
+```
+
+The `exitOnError` option can also be a function to prevent exit on only
+certain types of errors:
+
+``` js
+function ignoreEpipe(err) {
+  return err.code !== 'EPIPE';
+}
+
+const logger = winston.createLogger({ exitOnError: ignoreEpipe });
+
+//
+// or, like this:
+//
+logger.exitOnError = ignoreEpipe;
+```
+
+## Rejections
+
+### Handling Uncaught Promise Rejections with winston
+
+With `winston`, it is possible to catch and log `unhandledRejection` events
+from your process. With your own logger instance you can enable this behavior
+when it's created or later on in your applications lifecycle:
+
+``` js
+const { createLogger, transports } = require('winston');
+
+// Enable rejection handling when you create your logger.
+const logger = createLogger({
+  transports: [
+    new transports.File({ filename: 'combined.log' })
+  ],
+  rejectionHandlers: [
+    new transports.File({ filename: 'rejections.log' })
+  ]
+});
+
+// Or enable it later on by adding a transport or using `.rejections.handle`
+const logger = createLogger({
+  transports: [
+    new transports.File({ filename: 'combined.log' })
+  ]
+});
+
+// Call rejections.handle with a transport to handle rejections
+logger.rejections.handle(
+  new transports.File({ filename: 'rejections.log' })
+);
+```
+
+If you want to use this feature with the default logger, simply call
+`.rejections.handle()` with a transport instance.
+
+``` js
+//
+// You can add a separate rejection logger by passing it to `.rejections.handle`
+//
+winston.rejections.handle(
+  new winston.transports.File({ filename: 'path/to/rejections.log' })
+);
+
+//
+// Alternatively you can set `handleRejections` to true when adding transports
+// to winston.
+//
+winston.add(new winston.transports.File({
+  filename: 'path/to/combined.log',
+  handleRejections: true
+}));
+```
+
+## Profiling
+
+In addition to logging messages and metadata, `winston` also has a simple
+profiling mechanism implemented for any logger:
+
+``` js
+//
+// Start profile of 'test'
+//
+logger.profile('test');
+
+setTimeout(function () {
+  //
+  // Stop profile of 'test'. Logging will now take place:
+  //   '17 Jan 21:00:00 - info: test duration=1000ms'
+  //
+  logger.profile('test');
+}, 1000);
+```
+
+Also you can start a timer and keep a reference that you can call `.done()`
+on:
+
+``` js
+ // Returns an object corresponding to a specific timing. When done
+ // is called the timer will finish and log the duration. e.g.:
+ //
+ const profiler = logger.startTimer();
+ setTimeout(function () {
+   profiler.done({ message: 'Logging message' });
+ }, 1000);
+```
+
+All profile messages are set to 'info' level by default, and both message and
+metadata are optional.  For individual profile messages, you can override the default log level by supplying a metadata object with a `level` property:
+
+```js
+logger.profile('test', { level: 'debug' });
+```
+
+## Querying Logs
+
+`winston` supports querying of logs with Loggly-like options. [See Loggly
+Search API](https://www.loggly.com/docs/api-retrieving-data/). Specifically:
+`File`, `Couchdb`, `Redis`, `Loggly`, `Nssocket`, and `Http`.
+
+``` js
+const options = {
+  from: new Date() - (24 * 60 * 60 * 1000),
+  until: new Date(),
+  limit: 10,
+  start: 0,
+  order: 'desc',
+  fields: ['message']
+};
+
+//
+// Find items logged between today and yesterday.
+//
+logger.query(options, function (err, results) {
+  if (err) {
+    /* TODO: handle me */
+    throw err;
+  }
+
+  console.log(results);
+});
+```
+
+## Streaming Logs
+Streaming allows you to stream your logs back from your chosen transport.
+
+``` js
+//
+// Start at the end.
+//
+winston.stream({ start: -1 }).on('log', function(log) {
+  console.log(log);
+});
+```
+
+## Further Reading
+
+### Using the Default Logger
+
+The default logger is accessible through the `winston` module directly. Any
+method that you could call on an instance of a logger is available on the
+default logger:
+
+``` js
+const winston = require('winston');
+
+winston.log('info', 'Hello distributed log files!');
+winston.info('Hello again distributed logs');
+
+winston.level = 'debug';
+winston.log('debug', 'Now my debug messages are written to console!');
+```
+
+By default, no transports are set on the default logger. You must
+add or remove transports via the `add()` and `remove()` methods:
+
+``` js
+const files = new winston.transports.File({ filename: 'combined.log' });
+const console = new winston.transports.Console();
+
+winston.add(console);
+winston.add(files);
+winston.remove(console);
+```
+
+Or do it with one call to configure():
+
+``` js
+winston.configure({
+  transports: [
+    new winston.transports.File({ filename: 'somefile.log' })
+  ]
+});
+```
+
+For more documentation about working with each individual transport supported
+by `winston` see the [`winston` Transports](docs/transports.md) document.
+
+### Awaiting logs to be written in `winston`
+
+Often it is useful to wait for your logs to be written before exiting the
+process. Each instance of `winston.Logger` is also a [Node.js stream]. A
+`finish` event will be raised when all logs have flushed to all transports
+after the stream has been ended.
+
+``` js
+const transport = new winston.transports.Console();
+const logger = winston.createLogger({
+  transports: [transport]
+});
+
+logger.on('finish', function (info) {
+  // All `info` log messages has now been logged
+});
+
+logger.info('CHILL WINSTON!', { seriously: true });
+logger.end();
+```
+
+It is also worth mentioning that the logger also emits an 'error' event
+if an error occurs within the logger itself which
+you should handle or suppress if you don't want unhandled exceptions:
+
+``` js
+//
+// Handle errors originating in the logger itself
+//
+logger.on('error', function (err) { /* Do Something */ });
+```
+
+### Working with multiple Loggers in winston
+
+Often in larger, more complex, applications it is necessary to have multiple
+logger instances with different settings. Each logger is responsible for a
+different feature area (or category). This is exposed in `winston` in two
+ways: through `winston.loggers` and instances of `winston.Container`. In fact,
+`winston.loggers` is just a predefined instance of `winston.Container`:
+
+``` js
+const winston = require('winston');
+const { format } = winston;
+const { combine, label, json } = format;
+
+//
+// Configure the logger for `category1`
+//
+winston.loggers.add('category1', {
+  format: combine(
+    label({ label: 'category one' }),
+    json()
+  ),
+  transports: [
+    new winston.transports.Console({ level: 'silly' }),
+    new winston.transports.File({ filename: 'somefile.log' })
+  ]
+});
+
+//
+// Configure the logger for `category2`
+//
+winston.loggers.add('category2', {
+  format: combine(
+    label({ label: 'category two' }),
+    json()
+  ),
+  transports: [
+    new winston.transports.Http({ host: 'localhost', port:8080 })
+  ]
+});
+```
+
+Now that your loggers are setup, you can require winston _in any file in your
+application_ and access these pre-configured loggers:
+
+``` js
+const winston = require('winston');
+
+//
+// Grab your preconfigured loggers
+//
+const category1 = winston.loggers.get('category1');
+const category2 = winston.loggers.get('category2');
+
+category1.info('logging to file and console transports');
+category2.info('logging to http transport');
+```
+
+If you prefer to manage the `Container` yourself, you can simply instantiate one:
+
+``` js
+const winston = require('winston');
+const { format } = winston;
+const { combine, label, json } = format;
+
+const container = new winston.Container();
+
+container.add('category1', {
+  format: combine(
+    label({ label: 'category one' }),
+    json()
+  ),
+  transports: [
+    new winston.transports.Console({ level: 'silly' }),
+    new winston.transports.File({ filename: 'somefile.log' })
+  ]
+});
+
+const category1 = container.get('category1');
+category1.info('logging to file and console transports');
+```
+
+### Routing Console transport messages to the console instead of stdout and stderr
+
+By default the `winston.transports.Console` transport sends messages to `stdout` and `stderr`. This
+is fine in most situations; however, there are some cases where this isn't desirable, including:
+
+- Debugging using VSCode and attaching to, rather than launching, a Node.js process
+- Writing JSON format messages in AWS Lambda
+- Logging during Jest tests with the `--silent` option
+
+To make the transport log use `console.log()`, `console.warn()` and `console.error()`
+instead, set the `forceConsole` option to `true`:
+
+```js
+const logger = winston.createLogger({
+  level: 'info',
+  transports: [new winston.transports.Console({ forceConsole: true })]
+});
+```
+
+## Installation
+
+``` bash
+npm install winston
+```
+
+``` bash
+yarn add winston
+```
+
+## Run Tests
+
+All of the winston tests are written with [`mocha`][mocha], [`nyc`][nyc], and
+[`assume`][assume].  They can be run with `npm`.
+
+``` bash
+npm test
+```
+
+#### Author: [Charlie Robbins]
+#### Contributors: [Jarrett Cruger], [David Hyde], [Chris Alderson]
+
+[Transports]: #transports
+[Logging levels]: #logging-levels
+[Formats]: #formats
+[Using custom logging levels]: #using-custom-logging-levels
+[Adding Custom Transports]: #adding-custom-transports
+[core transports]: docs/transports.md#winston-core
+[additional transports]: docs/transports.md#additional-transports
+
+[RFC5424]: https://tools.ietf.org/html/rfc5424
+[util.format]: https://nodejs.org/dist/latest/docs/api/util.html#util_util_format_format_args
+[mocha]: https://mochajs.org
+[nyc]: https://github.com/istanbuljs/nyc
+[assume]: https://github.com/bigpipe/assume
+[logform]: https://github.com/winstonjs/logform#readme
+[winston-transport]: https://github.com/winstonjs/winston-transport
+
+[Read the `winston@2.x` documentation]: https://github.com/winstonjs/winston/tree/2.x
+
+[quick-example]: https://github.com/winstonjs/winston/blob/master/examples/quick-start.js
+[examples]: https://github.com/winstonjs/winston/tree/master/examples
+
+[Charlie Robbins]: http://github.com/indexzero
+[Jarrett Cruger]: https://github.com/jcrugzz
+[David Hyde]: https://github.com/dabh
+[Chris Alderson]: https://github.com/chrisalderson