Winston

https://github.com/winstonjs/winston
Admin
Winston is a versatile logging library for Node.js applications, designed to be simple and universal...
Tokens:90,469
Snippets:629
Trust Score:7.6
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### File Transport Events and Example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-file.md

Documentation of the events emitted by the winston File transport and an example of a full rotation setup.

```APIDOC
## Events

- `'logged'` (per write)
- `'open'` (fullpath)
- `'flush'`
- `'closed'` (from `close()`)
- `'finish'` (from `finishIfEnding`/`_final`)
- `'fileclosed'` (lazy rotation)
- `'error'` (fs errors from `open`/`stat`/stream errors)

## Example — Full Rotation Setup

```js
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.printf(info => `${info.message}`),
  transports: [
    new winston.transports.File({
      filename: 'error.log',
      level: 'info',
      maxsize: 500,
      maxFiles: 3,
      zippedArchive: true,
      tailable: true
    })
  ]
});
```

## Type Declarations

`FileTransportOptions` and `FileTransportInstance` — see [types.md](../types.md).
```

--------------------------------

### Install winston with Yarn

Source: https://github.com/winstonjs/winston/blob/master/README.md

Installs the winston logging library using Yarn.

```bash
yarn add winston
```

--------------------------------

### Install winston with npm

Source: https://github.com/winstonjs/winston/blob/master/README.md

Installs the winston logging library using npm.

```bash
npm install winston
```

--------------------------------

### File transport rotation setup

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-file.md

Full rotation setup from examples/file-maxsize.js. Configures a File transport with maxsize, maxFiles, zippedArchive, and tailable options for log rotation.

```javascript
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.printf(info => `${info.message}`),
  transports: [
    new winston.transports.File({
      filename: 'error.log',
      level: 'info',
      maxsize: 500,
      maxFiles: 3,
      zippedArchive: true,
      tailable: true
    })
  ]
});
```

--------------------------------

### Container get method

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/container.md

The get method is identical to add, returning the existing logger or creating it on first call.

```javascript
get(id, options) {
  return this.add(id, options);
}
```

--------------------------------

### Profiler usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/profiler.md

Example usage of the Profiler: start a timer with logger.startTimer(), perform work, then call done with a metadata object. The done method writes a log entry with durationMs.

```js
const timer = logger.startTimer();

// ... work ...

timer.done({ message: 'Logging message' });
```

--------------------------------

### Example 1: Custom logger with exceptionHandlers

Source: https://github.com/winstonjs/winston/blob/master/README.md

Example 1: Configures a custom logger with a File transport for normal logs and a separate File transport in exceptionHandlers for uncaught exceptions.

```javascript
const logger = winston.createLogger({
  transports: [
    new winston.transports.File({ filename: 'path/to/combined.log' })
  ],
  exceptionHandlers: [
    new winston.transports.File({ filename: 'path/to/exceptions.log' })
  ]
});
```

--------------------------------

### Using transport.stream

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-http.md

Example usage of the stream method. It creates a stream with the 'start' option set to -1, listens for 'log' and 'error' events, and destroys the stream after 10 seconds.

```javascript
const stream = transport.stream({ start: -1 });
stream.on('log', json => console.log(json));
stream.on('error', err => console.error(err));
setTimeout(() => stream.destroy(), 10000);
```

--------------------------------

### profile method and usage

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger-query.md

The profile method signature and an example of profiling a database query. The first call with an id records the start time, the second call with the same id logs the duration.

```js
profile(id, ...args) { ... }
```

```js
logger.profile('db-query');
db.query(...).then(result => {
  logger.profile('db-query', { message: 'db-query completed' }); // logs durationMs
});
```

--------------------------------

### Logger with rejectionHandlers example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/rejection-handler.md

Example of creating a logger with rejectionHandlers and exitOnError false. A rejected promise is logged to the file and the process survives.

```javascript
const logger = winston.createLogger({
  transports: [new winston.transports.Console()],
  rejectionHandlers: [new winston.transports.File({ filename: 'rejections.log' })],
  exitOnError: false
});

Promise.reject(new Error('async failure')); // logged to file, process survives
```

--------------------------------

### Profile with logger.profile()

Source: https://github.com/winstonjs/winston/blob/master/README.md

Demonstrates the basic profiling mechanism: call logger.profile('test') to start, then call it again after a delay to stop and log the duration at info level.

```javascript
//
// 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);
```

--------------------------------

### stream method signature and usage

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-file.md

The stream method signature and a usage example. The method returns a readable stream that emits 'data' and 'log' events, with errors emitted as 'error'. The example starts from the beginning and destroys the stream after 10 seconds.

```js
stream(options = {}) { ... }
```

```js
const stream = transport.stream({ start: -1 });
stream.on('log', line => console.log(line));
stream.on('error', err => console.error(err));
setTimeout(() => stream.destroy(), 10000);
```

--------------------------------

### winston module

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/winston-module.md

Documentation for the winston module entry point, including exports, default logger, and usage examples.

```APIDOC
## [MODULE] winston

### Description
The top-level module returned by `require('winston')`. It re-exports all core components and provides a default logger with pass-through methods and property proxies.

### Import
```js
const winston = require('winston');
```

### Exports
| Export | Type | Description |
|---|---|---|
| `version` | `string` | Package version |
| `transports` | `{ Console, File, Http, Stream }` | Transport classes |
| `config` | `{ cli, npm, syslog, addColors }` | Logging configurations |
| `addColors` | `function` | Alias of `logform.levels` |
| `format` | `function` | Alias of `logform.format` |
| `createLogger` | `function(opts?) → Logger` | Creates a new logger |
| `Logger` | `class` | Logger class |
| `ExceptionHandler` | `class` | Exception handler class |
| `RejectionHandler` | `class` | Rejection handler class |
| `Container` | `class` | Container class |
| `Transport` | `class` | Transport class |
| `loggers` | `Container` instance | Pre-built container for named loggers |

### Default Logger
Created with no options: no transports, npm levels, `level: 'info'`, logform JSON format. Starts with zero transports, so add transports before logging.

#### Pass-through Methods
`log`, `query`, `stream`, `add`, `remove`, `clear`, `profile`, `startTimer`, `handleExceptions`, `unhandleExceptions`, `handleRejections`, `unhandleRejections`, `configure`, `child`, plus `error`, `warn`, `info`, `http`, `verbose`, `debug`, `silly`.

#### Property Proxies
| Property | Behavior |
|---|---|
| `winston.level` | get/set → `defaultLogger.level` |
| `winston.exceptions` | get → `defaultLogger.exceptions` |
| `winston.rejections` | get → `defaultLogger.rejections` |
| `winston.exitOnError` | get/set → `defaultLogger.exitOnError` |
| `winston.default` | get → `{ exceptionHandlers, rejectionHandlers, transports }` |

### Usage Example
```js
const winston = require('winston');

winston.add(new winston.transports.Console({ format: winston.format.simple() }));
winston.level = 'debug';

winston.log('info', 'Hello distributed log files!');
winston.info('Hello again distributed logs');
winston.debug('Now my debug messages are written to console!');
```

### Configure Default Logger
```js
winston.configure({
  transports: [new winston.transports.File({ filename: 'somefile.log' })]
});
```

### Shared Named Loggers
```js
// some-file1.js
const logger = require('winston').loggers.get('something');
// some-file2.js — same underlying Logger instance
const logger = require('winston').loggers.get('something');
```

### Removed-API Stubs
The following properties/functions exist but deliberately throw when touched: `setLevels`, `cli`, `addRewriter`, `addFilter`, `clone`, `extend`, `padLevels`, `stripColors`, `emitErrs`, `levelLength`.
```

--------------------------------

### logger.log usage examples

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger.md

Examples of calling logger.log with different argument forms. The last example requires winston.format.splat() to interpolate the format specifiers.

```javascript
logger.log('info', 'Hello world', { custom: true });
logger.log('info', new Error('it is on fire'));
logger.log({ level: 'info', message: 'Hello world', custom: true });

// Requires winston.format.splat():
logger.log('info', '%s %d%%', 'A string', 50, { thisIsMeta: true });
```

--------------------------------

### Stream logs with winston.stream and start: -1

Source: https://github.com/winstonjs/winston/blob/master/README.md

Stream logs from the chosen transport. Starting with start: -1 begins at the end of the log stream. The 'log' event handler prints each log entry.

```javascript
//
// Start at the end.
//
winston.stream({ start: -1 }).on('log', function(log) {
  console.log(log);
});
```

--------------------------------

### startTimer method and usage

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger-query.md

The startTimer method returns a new Profiler instance. The example shows how to use it: start a timer, then call timer.done() after some async work to log a message with durationMs.

```js
startTimer() {
  return new Profiler(this);
}
```

```js
const timer = logger.startTimer();
setTimeout(() => {
  timer.done({ message: 'Logging message' });   // logs { level: 'info', durationMs: <ms>, message: ... }
}, 1000);
```

--------------------------------

### close() method and usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger.md

The close method implementation and an example of listening for the 'close' event. The method unregisters process-level exception/rejection handlers, cleans up all transports, and emits 'close'.

```js
close() {
  this.exceptions.unhandle();
  this.rejections.unhandle();
  this.clear();
  this.emit('close');
  return this;
}
```

```js
logger.on('close', () => console.log('logger closed'));
logger.close();
```

--------------------------------

### createLogger(opts)

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/create-logger.md

Documentation for the createLogger factory function, including its signature, behavior, and usage examples.

```APIDOC
## createLogger(opts)

### Description
Factory function that creates a `Logger` instance with one prototype method per configured log level. It is the primary way to instantiate a logger in winston.

### Method
Function call (not constructor)

### Endpoint
`createLogger(opts)`

### Parameters
- **opts** (LoggerOptions) - Optional - Configuration object compatible with `LoggerOptions`. Defaults to `{}`.

### Returns
- **Logger** - A newly created logger instance.

### Behavior
- `opts.levels` defaults to `config.npm.levels`.
- For every key in `opts.levels`, two prototype methods are defined on the logger:
  - `logger.<level>(...)` - logs at that level.
  - `logger.is<Level>Enabled()` - returns whether that level is enabled (e.g., `isInfoEnabled()`).
- If a level is named `"log"`, it is skipped with a warning.

### Level-method argument handling
- `logger.info(obj)` - if `obj` has a `message` property, logs `obj`; otherwise logs `{ message: obj }`.
- `logger.info()` - logs an empty string.
- `logger.info(msg, ...rest)` - delegates to `self.log(level, ...args)` supporting v1/v2/v3 API shapes, splat interpolation, and metadata.

### Example
```js
const { createLogger, format, transports } = require('winston');

const logger = createLogger({
  level: 'info',
  format: format.json(),
  defaultMeta: { service: 'user-service' },
  transports: [new transports.File({ filename: 'combined.log' })]
});

logger.info('hello');            // { message: 'hello', level: 'info', service: 'user-service', ... }
logger.isInfoEnabled();          // true
```
```

--------------------------------

### Example 2: Custom logger with Console handleExceptions and exitOnError

Source: https://github.com/winstonjs/winston/blob/master/README.md

Example 2: Configures a custom logger with a Console transport that handles exceptions (handleExceptions: true) and sets exitOnError to false to prevent process exit.

```javascript
const logger = winston.createLogger({
  transports: [
    new winston.transports.Console({
      handleExceptions: true
    })
  ],
  exitOnError: false
});
```

--------------------------------

### Profile with logger.startTimer() and profiler.done()

Source: https://github.com/winstonjs/winston/blob/master/README.md

Shows how to use logger.startTimer() to get a profiler object and call .done() to finish timing and log the duration with an optional message.

```javascript
 // 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);
```

--------------------------------

### get(id, options)

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/container.md

Retrieves a logger by id, creating it if it doesn't exist. Identical to `add`.

```APIDOC
## get(id, options)

### Description
Retrieves a logger by id. If the logger does not exist, it is created with the provided options (or the container's default options). This method is identical to `add`.

### Method
get

### Parameters
#### Parameters
- **id** (string) - Required - The id of the Logger to find or create.
- **options** (LoggerOptions) - Optional - Created-on-first-call options.

### Request Example
```js
const logger = winston.loggers.get('worker-a'); // created on first call
const again = winston.loggers.get('worker-a');  // cached instance
```

### Response
#### Success Response
Returns the Logger instance (either newly created or existing).
```

--------------------------------

### Managing multiple loggers with winston.Container

Source: https://github.com/winstonjs/winston/blob/master/README.md

Shows how to manage multiple loggers manually by instantiating a winston.Container and using its add() and get() methods. This is an alternative to using the predefined winston.loggers.

```javascript
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');
```

--------------------------------

### query usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-http.md

Calls the query method with options for the last day and descending order, logging the response or error.

```javascript
transport.query({ from: new Date(Date.now() - 864e5), order: 'desc' }, (err, body) => {
  if (err) return console.error(err);
  console.log(body);
});
```

--------------------------------

### startTimer

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger-query.md

Starts a timer that returns a Profiler instance for measuring and logging operation durations.

```APIDOC
## startTimer

### Description
Starts a timer that can be used to measure the duration of an operation and log it with a `durationMs` property.

### Method
`startTimer()`

### Endpoint
`logger.startTimer()`

### Returns
- **Profiler** - A Profiler instance that can be used to log the duration.

### Request Example
```js
const timer = logger.startTimer();
setTimeout(() => {
  timer.done({ message: 'Logging message' });   // logs { level: 'info', durationMs: <ms>, message: ... }
}, 1000);
```

### Notes
- Throws if called on a non-Logger receiver (Profiler validates `logger instanceof Logger`).
```

--------------------------------

### Opt single transport into rejection handling

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/rejection-handler.md

Alternative example opting a single transport into rejection handling via handleRejections: true.

```javascript
const logger = winston.createLogger({
  transports: [new winston.transports.Console({ handleRejections: true })],
  exitOnError: false
});
```

--------------------------------

### Using container.get

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/container.md

Gets a logger by id, creating it on first call. Subsequent calls return the cached instance.

```javascript
const logger = winston.loggers.get('worker-a'); // created on first call
const again = winston.loggers.get('worker-a');  // cached instance
```

--------------------------------

### Handle rejection with File transport

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/rejection-handler.md

Example usage of the handle method to register a File transport for rejection logging.

```javascript
logger.rejections.handle(new winston.transports.File({ filename: 'rejections.log' }));
```

--------------------------------

### Combine formats with format.combine and prettyPrint

Source: https://github.com/winstonjs/winston/blob/master/README.md

Combine multiple formats using format.combine. This example combines label, timestamp, and prettyPrint, then logs an object. The output shows the formatted log with the label and timestamp.

```javascript
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' }
```

--------------------------------

### Set level and format per transport

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports.md

Demonstrates setting `level` and `format` options on each transport when creating a logger. The example uses `File`, `Http`, and `Console` transports with different levels and formats.

```javascript
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()) })
  ]
});
```

--------------------------------

### Creating a Container instance

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/container.md

Shows how to import and instantiate a Container with default options. The options are applied to all loggers created by this container unless overridden.

```javascript
const { Container } = require('winston');
const container = new Container({ level: 'debug' });
```

--------------------------------

### configure() method signature with options

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger.md

Shows the full configure() signature with all options. This method resets transports and handlers, and applies new configuration. Note that colors, emitErrs, formatters, padLevels, rewriters, and stripColors throw in winston@3.0.0.

```javascript
configure({
  silent,
  format,
  defaultMeta,
  levels,
  level = 'info',
  exitOnError = true,
  transports,
  colors,
  emitErrs,
  formatters,
  padLevels,
  rewriters,
  stripColors,
  exceptionHandlers,
  rejectionHandlers
} = {}) { ... }
```

--------------------------------

### Using log() and level-specific methods

Source: https://github.com/winstonjs/winston/blob/master/README.md

Shows two ways to set the logging level: passing a string to the log() method or using level-specific methods (e.g., logger.info). Includes examples for both a logger instance and the default 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");
```

--------------------------------

### Entry point surface

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/overview.md

Overview of the winston entry point surface, including exports, default logger methods, property proxies, and removed APIs.

```APIDOC
## Entry point surface (`lib/winston.js`)

```js
exports.version      // string, package version
exports.transports   // { Console, File, Http, Stream }
exports.config       // { cli, npm, syslog, addColors }
exports.addColors    // = logform.levels
exports.format       // = logform.format
exports.createLogger // factory function
exports.Logger       // Logger class
exports.ExceptionHandler
exports.RejectionHandler
exports.Container
exports.Transport    // = require('winston-transport')
exports.loggers      // = new Container()  — shared named logger registry
```

`winston.loggers` is a pre-built `Container` so programs can share named loggers: `winston.loggers.get('name')` in any module.

A **default logger** is created via `exports.createLogger()` (no transports, default `level: 'info'`, npm levels, JSON format) and the following methods are forwarded to it with `(...args) => defaultLogger[method](...args)`: all npm level names (`error`, `warn`, `info`, `http`, `verbose`, `debug`, `silly`) plus `log`, `query`, `stream`, `add`, `remove`, `clear`, `profile`, `startTimer`, `handleExceptions`, `unhandleExceptions`, `handleRejections`, `unhandleRejections`, `configure`, `child` (`lib/winston.js:80-94`).

Property proxies on the entry point (`lib/winston.js:97-150`): `winston.level` (get/set → default logger), `winston.exceptions`, `winston.rejections` (get → default logger handlers), `winston.exitOnError` (get/set), and `winston.default` (get → `{ exceptionHandlers, rejectionHandlers, transports }` of the default logger).

**Deliberately broken (removed) APIs** — the entry point installs throwing stubs (see [errors.md](errors.md)) for: `winston.setLevels`, `winston.cli`, `winston.padLevels`, `winston.stripColors`, `winston.addRewriter`, `winston.addFilter`, `winston.clone`, `winston.extend`, `winston.emitErrs`, `winston.levelLength` (`lib/winston.js:174-183`).
```

--------------------------------

### logger.stream usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger-query.md

Example usage of logger.stream to listen for log and error events, and destroy the stream after 5 seconds.

```js
const stream = logger.stream({ start: -1 });
stream.on('log', log => console.log(log));
stream.on('error', err => console.error(err));
setTimeout(() => stream.destroy(), 5000);
```

--------------------------------

### new transports.File(options = {})

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/configuration.md

Documentation for the File transport constructor and its options.

```APIDOC
## [CONSTRUCTOR] new transports.File(options = {})

### Description
Creates a new File transport instance that writes log messages to a file. Requires `filename`/`dirname` or `stream`. Accepts the base TransportStreamOptions as well as File-specific options.

### Constructor
`new transports.File(options = {})`

### Parameters
#### Options Object
- **filename** (string) - Either-or with `dirname`/`stream` - Log file name; basename-stripped. Default: `'winston.log'` (basename of `filename`).
- **dirname** (string) - Optional - Directory; created recursively if missing. Default: `path.dirname(filename)`.
- **options** (object) - Optional - Options passed to `fs.createWriteStream`. Default: `{ flags: 'a' }`.
- **stream** (NodeJS.WritableStream) - Optional - Legacy mode — **deprecated**, warns `'options.stream will be removed in winston@4. Use winston.transports.Stream'`; cannot combine with `filename`/`maxsize`.
- **maxsize** (number) - Optional - Rotate when the file reaches this byte size. Default: `null`.
- **rotationFormat** (Function) - Optional - Returns the numeric rotation suffix (`_getFile`, `file.js:692-713`). Default: `false`.
- **zippedArchive** (boolean) - Optional - gzip rotated files to `.gz`. Default: `false`.
- **maxFiles** (number) - Optional - Cap on rotated files (incrementing or tailable rollover). Default: `null`.
- **eol** (string) - Optional - EOL appended to each record. Default: `os.EOL`.
- **tailable** (boolean) - Optional - Roll files forward (`file1.log`, `file2.log`, ...) instead of timestamped suffixes. Default: `false`.
- **lazy** (boolean) - Optional - Open the file lazily on first write. Default: `false`.

### Inherited Options
- **level** (string) - Optional - Per-transport minimum level.
- **silent** (boolean) - Optional - If true, suppresses output.
- **format** (Format) - Optional - Per-transport format.
- **handleExceptions** (boolean) - Optional - Handle uncaught exceptions.
- **handleRejections** (boolean) - Optional - Handle unhandled rejections.

### Example
```js
const { transports } = require('winston');
const fileTransport = new transports.File({
  filename: 'app.log',
  dirname: 'logs',
  maxsize: 1048576,
  zippedArchive: true
});
```
```

--------------------------------

### Console transport _stringArrayToSet error example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-console.md

Example showing that passing a non-array to _stringArrayToSet throws an error with the default message.

```javascript
try {
  transport._stringArrayToSet('error'); // throws
} catch (err) {
  console.error(err.message); // 'Cannot make set from type other than Array of string elements'
}
```

--------------------------------

### Create custom logger with cli levels and addColors

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/config.md

Shows how to create a logger using the cli level set and how to add custom colors for levels. addColors must be called before the colorize() format is used.

```javascript
const winston = require('winston');

// Custom logger using the cli level set
const logger = winston.createLogger({
  levels: winston.config.cli.levels,
  transports: [new winston.transports.Console()]
});
logger.prompt('everything is fine');

// Colorize custom levels
winston.addColors({
  error: 'red',
  warn: 'yellow',
  info: 'green',
  http: 'magenta',
  verbose: 'cyan',
  debug: 'blue',
  silly: 'grey'
});
```

--------------------------------

### isLevelEnabled usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger-query.md

Example usage of isLevelEnabled with the level 'debug'. The comment indicates it returns true when the level passes the enabled check.

```javascript
logger.isLevelEnabled('debug'); // true when level 'debug' passes
```

--------------------------------

### constructor

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/container.md

Creates a new Container instance with optional default options applied to all loggers created by this container.

```APIDOC
## constructor

### Description
Creates a new Container instance. The `options` parameter provides default pass-through options applied to every logger created by this container when the caller doesn't pass their own.

### Method
constructor

### Parameters
#### Parameters
- **options** (LoggerOptions) - Optional - Default: `{}` - Default pass-through options applied to every logger created by this container.

### Request Example
```js
const { Container } = require('winston');
const container = new Container({ level: 'debug' });
```

### Response
#### Success Response
Returns a new Container instance.
```

--------------------------------

### getHighestLogLevel usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger-query.md

Example usage of getHighestLogLevel with a Console transport configured at level 'warn'. The comment indicates the call returns the highest enabled severity number.

```javascript
const logger = createLogger({
  transports: [new transports.Console({ level: 'warn' })]
});
logger.getHighestLogLevel(); // highest enabled severity number
```

--------------------------------

### getOsInfo()

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/rejection-handler.md

Returns OS information including loadavg and uptime.

```APIDOC
## getOsInfo()

### Description
Returns OS information including loadavg and uptime.

### Method
getOsInfo

### Parameters
None

### Request Example
```js
const osInfo = logger.rejections.getOsInfo();
```

### Response
#### Success Response
Returns an object with fields: `loadavg` (array), `uptime` (number).
```

--------------------------------

### getAllInfo(err)

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/rejection-handler.md

Builds the info object logged for a rejection. Includes error details, level, message, stack, rejection flag, date, process info, OS info, and trace.

```APIDOC
## getAllInfo(err)

### Description
Builds the info object logged for a rejection. Includes error details, level, message, stack, rejection flag, date, process info, OS info, and trace.

### Method
getAllInfo

### Parameters
- **err** (string | Error) - Optional - The rejected value (error or message string)

### Request Example
```js
const info = logger.rejections.getAllInfo(new Error('async failure'));
```

### Response
#### Success Response
Returns an object with the following fields:
- **error** (Error | null) - The original rejection value
- **level** (string) - Always `'error'`
- **message** (string) - `unhandledRejection: ${message}` + '\n' + stack (or '  No stack trace')
- **stack** (string | undefined) - `err.stack` when present
- **rejection** (boolean) - `true`
- **date** (string) - `new Date().toString()`
- **process** (object) - `getProcessInfo()`
- **os** (object) - `getOsInfo()`
- **trace** (object[]) - `getTrace(err)`

#### Response Example
```js
{
  error: Error,
  level: 'error',
  message: 'unhandledRejection: async failure\n    at ...',
  stack: 'Error: async failure\n    at ...',
  rejection: true,
  date: 'Mon Jan 01 2024 00:00:00 GMT+0000 (Coordinated Universal Time)',
  process: { pid: 123, uid: 0, gid: 0, cwd: '/path', execPath: '/usr/bin/node', version: 'v18.0.0', argv: [], memoryUsage: { rss: 123 } },
  os: { loadavg: [0, 0, 0], uptime: 100 },
  trace: [{ column: 1, file: 'app.js', function: 'foo', line: 1, method: null, native: false }]
}
```
```

--------------------------------

### new transports.Http(options)

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-http.md

Documentation for the Http transport constructor, including its options and behavior.

```APIDOC
## [CONSTRUCTOR] new transports.Http(options)

### Description
Creates a new instance of the Http transport, which persists log messages to a JSON-RPC-style HTTP server. The constructor sets up the transport's configuration, including host, port, authentication, batching, and headers.

### Method
Constructor

### Endpoint
`new transports.Http(options)`

### Parameters
#### Constructor Options
- **options** (HttpTransportOptions) - Optional - Configuration options for the transport. Defaults to `{}`.
  - **name** (string) - Optional - Name of the transport. Defaults to `'http'`.
  - **ssl** (boolean) - Optional - Whether to use SSL. Defaults to `false`.
  - **host** (string) - Optional - Hostname of the HTTP server. Defaults to `'localhost'`.
  - **port** (number) - Optional - Port of the HTTP server. If not set, defaults to `443` when `ssl` is true, otherwise `80`.
  - **auth** (object) - Optional - Authentication credentials.
  - **path** (string) - Optional - Path to append to the server URL. Defaults to `''`.
  - **maximumDepth** (number) - Optional - Maximum depth for serializing log messages.
  - **agent** (object) - Optional - HTTP agent to use.
  - **headers** (object) - Optional - Additional headers to send. The `content-type` header is forced to `application/json`.
  - **batch** (boolean) - Optional - Whether to enable batching. Defaults to `false`.
  - **batchInterval** (number) - Optional - Interval in milliseconds for batch flushing. Defaults to `5000`.
  - **batchCount** (number) - Optional - Maximum number of logs per batch. Defaults to `10`.

### Request Example
```js
const { transports } = require('winston');
const transport = new transports.Http({
  host: 'localhost',
  port: 8080,
  path: '/log',
  ssl: false,
  batch: true,
  batchInterval: 1000,
  batchCount: 5
});
```

### Response
No return value. The constructor initializes the transport instance.

### Notes
- The `content-type` header is always set to `application/json`.
- If `port` is not provided, it is derived from the `ssl` option: `443` for HTTPS, `80` for HTTP.
```

--------------------------------

### logger.query usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger-query.md

Example usage of logger.query with options for time range, limit, and order. The callback receives an error or the aggregated results object keyed by transport name.

```js
logger.query({ from: new Date(Date.now() - 864e5), until: new Date(), limit: 10, order: 'desc' },
  (err, results) => {
    if (err) { /* transport query failed */ return; }
    console.log(results); // { 'file': [...], 'console': [...] }
  });
```

--------------------------------

### clear() method and usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger.md

The clear method implementation and an example of clearing all transports. The method returns `this` and removes all transports from the logger. After clearing, writing logs produces a warning on stderr.

```js
clear() {
  this.unpipe();
  return this;
}
```

```js
logger.clear();                 // no transports left
logger.info('nowhere to go');   // '[winston] Attempt to write logs with no transports...' on stderr
```

--------------------------------

### remove(transport) method and usage example

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger.md

The remove method signature and an example of removing a transport. The method returns `this` and is a no-op when `transport` is falsy. Note that a subsequent `error` event from a removed transport causes the logger to re-add it.

```js
remove(transport) { ... }
```

```js
logger.remove(file);
logger.transports; // pipes no longer include `file`
```

--------------------------------

### Using child() to create a logger with request metadata

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger.md

Example of creating a child logger with requestId metadata and writing info/warn logs. The child merges the metadata into each info before delegating to the parent's write.

```javascript
const parent = createLogger({ transports: [new transports.Console()] });
const child = parent.child({ requestId: 'abc-123' });
child.info('request started');           // gets { requestId: 'abc-123' }
child.log({ level: 'warn', message: 'slow' }); // same merge
```

--------------------------------

### Unhandle rejections

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/rejection-handler.md

Example usage of the unhandle method to remove rejection handling.

```javascript
logger.rejections.unhandle();
```

--------------------------------

### profile

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/logger-query.md

Starts or stops a profiler by ID, logging the duration on the second call.

```APIDOC
## profile

### Description
Starts or stops a profiler identified by an `id`. The first call with an `id` records the start time; the second call with the same `id` logs the duration.

### Method
`profile(id, ...args)`

### Endpoint
`logger.profile(id, ...args)`

### Parameters
#### Path Parameters
- **id** (string | number) - Required - Unique profiler key

#### Query Parameters
- **...args** (any[]) - Optional - Optional trailing metadata object; a function as 2nd-to-last arg is popped with a deprecation warning (callbacks no longer supported)

### Returns
- **this** (Logger) - The Logger instance.

### Request Example
```js
logger.profile('db-query');
db.query(...).then(result => {
  logger.profile('db-query', { message: 'db-query completed' }); // logs durationMs
});
```

### Notes
- First call with an `id` records `Date.now()` in `this.profilers[id]` and logs nothing.
- Second call with the same `id` builds `{ level: info.level || 'info', durationMs: Date.now() - start, message: info.message || id }` (merged with any trailing object metadata) and writes it.
```

--------------------------------

### open() method

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-file.md

Opens the file transport stream. No-op when there is no filename or _opening is already true. Stats the target file, sets _size, creates the destination write stream, emits 'open' with the full path, and resolves any rotation that occurred while opening.

```js
open() { ... }
```

--------------------------------

### winston.transports.Http

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-http.md

Example of creating a winston HTTP transport with batched delivery to a remote logging endpoint.

```APIDOC
## [POST] /api/logs

### Description
Creates an HTTP transport for winston that delivers log messages to a remote endpoint. Supports batched delivery to reduce network overhead.

### Method
POST

### Endpoint
https://logs.example.com/api/logs

### Parameters
#### Transport Options
- **host** (string) - Required - The hostname of the logging endpoint.
- **port** (number) - Required - The port of the logging endpoint.
- **ssl** (boolean) - Optional - Whether to use SSL/TLS.
- **path** (string) - Required - The path on the host to send logs to.
- **auth** (object) - Optional - Authentication credentials with `username` and `password` properties.
- **batch** (boolean) - Optional - Enable batched delivery.
- **batchInterval** (number) - Optional - Flush interval in milliseconds when batching.
- **batchCount** (number) - Optional - Maximum number of messages to accumulate before flushing.
- **agent** (any) - Optional - Custom HTTP agent.
- **headers** (object) - Optional - Additional HTTP headers.
- **replacer** (function) - Optional - JSON replacer function.
- **maximumDepth** (number) - Optional - Maximum depth for serializing log objects.

### Request Example
```js
const transport = new winston.transports.Http({
  host: 'logs.example.com',
  port: 443,
  ssl: true,
  path: '/api/logs',
  auth: { username: 'user', password: 'pass' },
  batch: true,
  batchInterval: 2000,   // flush every 2 s or...
  batchCount: 20         // ...when 20 messages accumulate
});
const logger = winston.createLogger({ transports: [transport] });
```

### Response
#### Success Response (200)
- **status** (string) - Success status of the log delivery.

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### getAllInfo

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/exception-handler.md

Builds the info object logged for an exception, including error details, process and OS information, and a trace.

```APIDOC
## getAllInfo

### Description
Builds the info object that will be logged for an exception. It includes error details, process and OS information, and a trace.

### Method
getAllInfo

### Endpoint
`getAllInfo(err)`

### Parameters
- **err** (string | Error) - Optional - The error or message string being handled.

### Returns
Returns an object with the following fields:
- **error** (Error | null) - The original error.
- **level** (string) - Always `'error'`.
- **message** (string) - `` `uncaughtException: ${message}` + '\n' + stack `` (or `'  No stack trace'`).
- **stack** (string | undefined) - `err.stack` when present.
- **exception** (boolean) - `true` - the predicate checked by `ExceptionStream`.
- **date** (string) - `new Date().toString()`.
- **process** (object) - `getProcessInfo()`.
- **os** (object) - `getOsInfo()`.
- **trace** (object[]) - `getTrace(err)`.

```

--------------------------------

### stat

Source: https://github.com/winstonjs/winston/blob/master/_autodocs/api-reference/transports-file.md

Stats the target file to get its current size, handling missing files and rotation triggers.

```APIDOC
## stat

### Description
Retrieves the current size of the target file. If the file does not exist, it confirms the current filename and returns a size of 0.

### Method
stat

### Signature
`stat(callback)`

### Parameters
- **callback** (Function) - Required - `(err, size)` — size in bytes of the current target file.

### Behavior
- `ENOENT` → confirm current filename, `callback(null, 0)`.
- Other stat errors → `callback(err)` (the constructor's `open()` re-emits as `'error'`).
- If the existing size already needs rotation, `_incFile` is invoked recursively.
```
Tokens:
Raw