What is npmlog?
The npmlog package is a logger for Node.js that is used by npm. It provides various logging levels and methods to output messages with different importance. It is designed to be both a core library for logging within npm itself as well as a tool for developers to use in their own applications.
What are npmlog's main functionalities?
Logging at different levels
npmlog provides methods to log messages at predefined levels such as info, warn, and error. Each level is associated with a method that takes a prefix and a message.
const log = require('npmlog');
log.info('info', 'This is an informational message');
log.warn('warn', 'This is a warning message');
log.error('error', 'This is an error message');
Custom log levels
Developers can define custom log levels with a specific numeric priority and styling options.
const log = require('npmlog');
log.addLevel('success', 2000, { fg: 'green', bold: true });
log.success('success', 'This is a success message');
Prefixing log messages
npmlog allows setting a global prefix that will be prepended to all log messages, which is useful for distinguishing logs from different parts of an application.
const log = require('npmlog');
log.heading = 'myapp';
log.info('info', 'This message will be prefixed with myapp');
Adjusting log output level
The verbosity of the log output can be controlled by setting the log.level property. Only messages at or above the specified level will be output.
const log = require('npmlog');
log.level = 'warn';
log.info('info', 'This message will not be printed');
log.warn('warn', 'This message will be printed');
Other packages similar to npmlog
winston
Winston is a multi-transport async logging library for Node.js. It is similar to npmlog but provides more flexibility in terms of transports (e.g., file, console, HTTP) and formatting options. It is well-suited for more complex logging needs.
bunyan
Bunyan is a simple and fast JSON logging library for Node.js services. It differs from npmlog by focusing on structured logging in JSON format, which is useful for processing logs with log management systems.
pino
Pino is a very low-overhead Node.js logger that outputs logs in JSON format. It is designed for performance and can be significantly faster than other logging libraries, including npmlog, especially in high-throughput scenarios.
debug
Debug is a tiny Node.js debugging utility that is similar to npmlog's logging capabilities but focuses on providing a simple way to debug code by enabling/disabling sets of logs using the DEBUG environment variable.
npmlog
The logger util that npm uses.
This logger is very basic. It does the logging for npm. It supports
custom levels and colored output.
By default, logs are written to stderr. If you want to send log messages
to outputs other than streams, then you can change the log.stream
member, or you can just listen to the events that it emits, and do
whatever you want with them.
Basic Usage
var log = require('npmlog')
// additional stuff ---------------------------+
// message ----------+ |
// prefix ----+ | |
// level -+ | | |
// v v v v
log.info('fyi', 'I have a kitty cat: %j', myKittyCat)
log.level
The level to display logs at. Any logs at or above this level will be
displayed. The special level silent
will prevent anything from being
displayed ever.
log.record
An array of all the log messages that have been entered.
log.maxRecordSize
The maximum number of records to keep. If log.record gets bigger than
10% over this value, then it is sliced down to 90% of this value.
The reason for the 10% window is so that it doesn't have to resize a
large array on every log entry.
log.prefixStyle
A style object that specifies how prefixes are styled. (See below)
log.headingStyle
A style object that specifies how the heading is styled. (See below)
log.heading
If set, a heading that is printed at the start of every line.
log.stream
- {Stream} Default:
process.stderr
The stream where output is written.
log.enableColor()
Force colors to be used on all messages, regardless of the output
stream.
log.disableColor()
Disable colors on all messages.
log.enableProgress()
Enable the display of log activity spinner and progress bar
log.disableProgress()
Disable the display of a progress bar
log.enableUnicode()
Force the unicode theme to be used for the progress bar.
log.disableUnicode()
Disable the use of unicode in the progress bar.
log.pause()
Stop emitting messages to the stream, but do not drop them.
log.resume()
Emit all buffered messages that were written while paused.
log.log(level, prefix, message, ...)
level
{String} The level to emit the message atprefix
{String} A string prefix. Set to "" to skip.message...
Arguments to util.format
Emit a log message at the specified level.
log[level](prefix, message, ...)
For example,
- log.silly(prefix, message, ...)
- log.verbose(prefix, message, ...)
- log.info(prefix, message, ...)
- log.http(prefix, message, ...)
- log.warn(prefix, message, ...)
- log.error(prefix, message, ...)
Like log.log(level, prefix, message, ...)
. In this way, each level is
given a shorthand, so you can do log.info(prefix, message)
.
log.addLevel(level, n, style, disp)
level
{String} Level indicatorn
{Number} The numeric levelstyle
{Object} Object with fg, bg, inverse, etc.disp
{String} Optional replacement for level
in the output.
Sets up a new level with a shorthand function and so forth.
Note that if the number is Infinity
, then setting the level to that
will cause all log messages to be suppressed. If the number is
-Infinity
, then the only way to show it is to enable all log messages.
log.newItem(name, todo, weight)
name
{String} Optional; progress item name.todo
{Number} Optional; total amount of work to be done. Default 0.weight
{Number} Optional; the weight of this item relative to others. Default 1.
This adds a new are-we-there-yet
item tracker to the progress tracker. The
object returned has the log[level]
methods but is otherwise an
are-we-there-yet
Tracker
object.
log.newStream(name, todo, weight)
This adds a new are-we-there-yet
stream tracker to the progress tracker. The
object returned has the log[level]
methods but is otherwise an
are-we-there-yet
TrackerStream
object.
log.newGroup(name, weight)
This adds a new are-we-there-yet
tracker group to the progress tracker. The
object returned has the log[level]
methods but is otherwise an
are-we-there-yet
TrackerGroup
object.
Events
Events are all emitted with the message object.
log
Emitted for all messageslog.<level>
Emitted for all messages with the <level>
level.<prefix>
Messages with prefixes also emit their prefix as an event.
Style Objects
Style objects can have the following fields:
fg
{String} Color for the foreground textbg
{String} Color for the backgroundbold
, inverse
, underline
{Boolean} Set the associated propertybell
{Boolean} Make a noise (This is pretty annoying, probably.)
Message Objects
Every log event is emitted with a message object, and the log.record
list contains all of them that have been created. They have the
following fields:
id
{Number}level
{String}prefix
{String}message
{String} Result of util.format()
messageRaw
{Array} Arguments to util.format()