# Class: Logger

The main class of this library. Provides methods for inheritance and logging.

# Events

Some transport types emit transport specific events on the logger they are attached to as well.

# Attributes

# scope

The scope of this logger.

Type: LoggerScope

# transformer

The transformers to apply to any payload of logs from this logger.

Type: ?Object

# transports

The transports to forward logs to.

Type: Transport[]

# ownChildPayloads

The default value whether payload ownership can be assumed to be given to oddlog for logging methods and child creation.

Type: Boolean

# messageFormatter

The function to call for primary log message formatting.

Type: {String} Function<String, ?Object|String...>

# Methods

TODO sort methods by similarity

# Logging methods

# Stateless

For each severity level, a method is provided as Logger#<level> (e.g. Logger#info) to create a log with that level.

Returns: this

Examples:

logger.info();         // log without log-specific payload and message
logger.info({});       // log with custom payload
logger.info(true, {}); // log with custom payload that is allowed to be modified by the logger (for performance
                       // gains)
// The following calls also accept additional formatting parameters.
logger.info("");           // log with primary (formatted) message text
logger.info({}, "");       // log with primary (formatted) message text and custom payload
logger.info(true, {}, ""); // log with primary (formatted) message text and custom payload that is allowed to be
                           // modified by the logger (for performance gains)

# Stateful

# setLevel

Sets the stateful level for calls of the Logger#log method. For each level an alias is provided as well as Logger#set<Level> (e.g. Logger#setInfo) without arguments.

Returns: this

# log

Create a new log with the current level. Same parameters as for the stateless methods.

Returns: this

# done

Resets the stateful level to the default level (can be specified within createLogger/defineLogger).

Returns: this

# getLevel

Returns: Number - The current stateful level.

# Guarding methods

For each severity level, a method is provided as Logger#is<Level> (e.g. Logger#isInfo) to check whether any transport might be interested in such logs.

Returns: Boolean - Whether (purely based on the level) any transport might be interested in logs of this level.

# child

Creates a child logger that inherits payload of this logger and uses the same options (such as transports).

Returns: Logger - The child logger.

Examples:

logger.child();                // a new logging child; E.g. to create dedicated TriggerTransport cache.
logger.child({});              // a new logging child with additional payload (merged into parent payload)
logger.child(true, {});        // a new logging child with additional payload that is allowed to be modified by the
                               // logger (for performance gains)
logger.child(true, true, {});  // a new logging child with additional payload that is allowed to be modified by the
                               // logger (for performance gains); Set `ownChildPayloads` for the child to `true` as well
logger.child(true, "sub", {}); // a new logging child with additional payload that is allowed to be modified by the
                               // logger (for performance gains); The child uses a dedicated logger scope with a
                               // suffixed name

# close

Closes the logger scope of this logger. This method must not be called on logger children (if they do not have a dedicated logger scope).

Returns: this

Examples:

logger.close();          // close the loggers scope
logger.close(false);     // close the loggers scope and throw an error on further attempts to log
logger.close(cb);        // close the loggers scope and call the callback when all messages have been flushed
logger.close(false, cb); // the two above combined

oddlog.closeAll(false, [log1, log2, ...], cb); // similar to methods above for multiple loggers

logger.exit(code);       // alias for `logger.close(() => process.exit(code));`

# exit

Closes the logger scope of this logger and calls process.exit when done.

Returns: this

# handleUncaughtExceptions

Registers an event handler to the uncaughtException event on process. The event handler gets removed when Logger#close gets called on the logger or any ancestor.

Returns: this

# handleUnhandledRejections

Registers an event handler to the unhandledRejection event on process. The event handler gets removed when Logger#close gets called on the logger or any ancestor.

Returns: this

# handleWarnings

Registers an event handler to the warning event on process. The event handler gets removed when Logger#close gets called on the logger or any ancestor.

Returns: this

# handleProcessEvents

Registers an event handler to the given event on process that logs logs the event data. The event handler gets removed when Logger#close gets called on the logger or any ancestor.

Returns: this

# addTransport

Creates a new transport and attaches it to this logger.

Returns: this

# addTransports

Creates new transports and attaches them to this logger.

Returns: this

# mergePayload

Merges additional payload into this loggers payload.

Returns: this

# getPreparedPayload

Prepares and caches the final payload of this logger (and inherited ones). According to the singleTransform option, the payload might also get transformed already. The result must not be modified.

Returns: ?Object|undefined - The finalized payload.

# mwExpress

Creates a middleware function to be used by express.js compatible routers. The middleware attaches a child logger to the request object as req.log.

Returns: Function<req, res, next> The middleware for express.js compatible routers.