Lightweight level based logging system.
LogLevel) - The default log level to use when calling the logger function stand alone (the usage examples below). Defaults to the lowest level,
LogLevel) - The maximum level, based on priority, to write to a stream. All levels higher than the maximum will be ignored. Defaults to allowing all levels.
Logging is based around the concept of a "logger", which provides a set of functions of severity
levels to log with. Logs are written to one or many provided transports -- or
console if not
defined. To begin, instantiate a logger with
createLogger, which returns a function that can be
used for standard level logging.
Each logging function requires a message string as the 1st argument, and an optional rest of arguments to interpolate into the message using util.format().
If you would prefer to interact with a class instance, you may use the
Logger class. The major
difference between the class and the function, is that the class only has 1 logging method,
The following options can be defined when creating a logger. They cannot be customized after the fact.
object) - A mapping of localized log level names. Can be used with chalk.
string) - Unique name of this logger instance, for debugging purposes. (Required)
Transportable) - List of transports in which to write formatted log messages to.
There are 5 distinct logging levels outside the standard level, each represented as a unique
function on the logger instance. The levels in order of priority are
error. Each function requires a message as the 1st argument, and an optional rest of
arguments to interpolate into the message.
By default, all logged messages are immediately written to the configured transports. To silence
output and disable writes, call the
logger.disable() function, and to re-enable, call
Messages that are logged while silenced are lost and are not buffered.
All logs are represented as an object, known as a log item. These items contain the following metadata about the environment, the logger, and the current log message.
string) - The host name of the machine.
string) - The log level as a localized or customized label.
LogLevel) - The log level as a string.
string) - The log message with interpolated arguments applied.
object) - Additional data to include with a log item.
string) - Name of the logger.
number) - Current process ID.
string) - Timestamp of the log, native to the host machine.
Before an item is written to a transport, it must be formatted from an object into a string. This
can be done on a per transport basis using the
format option, like so.
Boost provides formats by default, all of which are pre-configured into each built-in transport. Feel free to use the following built-in formats, or customize your own!
formats.console- Formats the item as if it's being logged to
console. Only inclues the label and message.
formats.debug- Formats the item into a human-readable message with all item fields included. This is the default format for most transports.
formats.json- Formats the entire item into JSON.
formats.message- Formats the item using only the message.
Sometimes additional metadata may be required that is not found within the pre-defined log item fields. Metadata can be defined on the logger using an object, which is then passed to all log items.
It can also be defined per log by passing an object as the 1st argument. Metadata defined at this level will override the logger metadata.
pidare reserved names and cannot be used.
There are multiple types of transports that can be used within a logger, all of which support the following shared options.
string) - End of line character to append to a message. Defaults to
Formatter) - Function to format a log item into a message string. Default is transport dependent.
LogLevel) - List of log levels to only write messages for. (Required)
Logs messages to the native
console and its corresponding level. This is the default transport
when no transports are defined.
Logs messages to any writeable stream or an object that defines a
write(message: string) method.
Appends and logs messages to a file at the defined path. Will automatically rotate files when a max file size is met.
boolean) - Apply gzip compression to the write stream.
number) - Maximum file size before rotating file. Will create a backup and truncate the current file. Defaults to 10mb.
string | Path) - Absolute file system path for the intended log file. (Required)
FileTransport, but also rotates files based on timestamps and a chosen periodic interval.
hourly | daily | weekly | monthly) - Period in which to rotate files. Will append a timestamp to the rotated log file.
The following Jest utilities are available in the
Returns a Jest spy that matches the return value shape of