log

What is log?

The 'log' npm package is a lightweight logging library for Node.js. It provides simple logging capabilities, allowing developers to output messages to the console with various levels of severity, such as debug, info, warn, and error. It is designed to be minimalistic and straightforward to use.

What are log's main functionalities?

Logging messages with different severity levels

This feature allows developers to log messages with different levels of importance. The 'log' package provides methods like debug, info, warn, and error to categorize log messages.

const log = require('log');
log.debug('Debug message');
log.info('Information message');
log.warn('Warning message');
log.error('Error message');

Custom log levels

Developers can set a custom log level to control which messages should be output. For example, setting the log level to 'error' will only output error messages, suppressing less severe messages.

const log = require('log');
log.level = 'debug';
log.debug('This debug message will be logged');
log.level = 'error';
log.debug('This debug message will NOT be logged');

Custom log output

The 'log' package allows developers to define a custom output function for log messages. This can be used to redirect log output to a file, a remote logging service, or any other custom handling.

const log = require('log');
log.use({ write: (message) => {/* Custom logic to output message */} });

Other packages similar to log

winston

Winston is a multi-transport async logging library for Node.js. It is more feature-rich than 'log', supporting multiple storage options, custom formats, and log rotation. It is suitable for more complex logging needs.

bunyan

Bunyan is a simple and fast JSON logging library for Node.js services. It includes features like log rotation, streams, and serializers. It is comparable to 'log' but focuses on structured logging in JSON format.

pino

Pino is a very low overhead Node.js logger, which is inspired by Bunyan. It focuses on performance and includes features like child loggers and custom serializers. It is an alternative to 'log' with a focus on high-performance use cases.

morgan

Morgan is an HTTP request logger middleware for Node.js. It is designed to log HTTP requests for web applications, especially in combination with frameworks like Express.js. It differs from 'log' by being specialized for HTTP context.

README

log

Universal logging utility

Configurable, environment and presentation agnostic, with log levels and namespacing (debug style) support

Usage

1. Write application/library logs

// Default logger (writes at 'info' level)
const log = require("log");

// Log 'info' level message:
log.info("some info message %s", "injected string");

// Get namespaced logger (debug lib style)
const myLibLog = log.get("my-lib");

// Log 'info' level message in context of 'my-lib' namespace:
myLibLog.info("some info message in 'my-lib' namespace context");

// Namespaces can be further nested
const myLibFuncLog = log.get("func");

// Log 'info' level message in context of 'my-lib:func' namespace:
myLibFuncLog.info("some info message in 'my-lib:func' namespace context");

// Log 'error' level message in context of 'my-lib:func' namespace:
myLibFuncLog.error("some error message");

// log output can be dynamically enabled/disabled during runtime
const { restore } = myLibFuncLog.error.disable();
myLibFuncLog.error("error message not really logged");
// Restore previous logs visibiity state
restore();
myLibFuncLog.error("error message to be logged");

2. Initialize log writer in main (starting) process module

e.g. if target is Node.js, then install log-node, and at the top of main module initialize it

require("log-node")();

Available log levels

Mirror of applicable syslog levels (in severity order):

• debug - debugging information (hidden by default)
• info - a purely informational message (hidden by default)
• notice - condition normal, but significant
• warning (also aliased as warn) - condition warning
• error - condition error - to notify of errors accompanied with recovery mechanism (hence reported as log and not as uncaught exception)

Note: critical, alert, emergency are not exposed as seem to not serve a use case in context of JS applications, such errors should be exposed as typical exceptions

Output message formatting

log doesn't force any specific arguments handling. Still it is recommended to assume printf-like message format, as all currently available writers are setup to support it. Placeholders support reflects one implemented in Node.js format util

Excerpt from Node.js documentation:

The first argument is a string containing zero or more placeholder tokens. Each placeholder token is replaced with the converted value from the corresponding argument. Supported placeholders are:

• %s - String.
• %d - Number (integer or floating point value).
• %i - Integer.
• %f - Floating point value.
• %j - JSON. Replaced with the string '[Circular]' if the argument contains circular references.
• %o - Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect() with options { showHidden: true, depth: 4, showProxy: true }. This will show the full object including non-enumerable symbols and properties.
• %O - Object. A string representation of an object with generic JavaScript object formatting. Similar to util.inspect() without options. This will show the full object not including non-enumerable symbols and properties.
• %% - single percent sign ('%'). This does not consume an argument.

Note to log writer configuration developers: For cross-env compatibility it is advised to base implementation on sprintf-kit

Enabling log writing

log on its own doesn't write anything to the console or any other means (it just emits events to be consumed by preloaded log writers).

To have logs written, the pre-chosen log writer needs to be initialized in the main (starting) module of a process.

List of available log writers

• log-node - For typical Node.js processes
• log-aws-lambda - For AWS lambda environment

Note: if some writer is missing, propose a PR

Logs Visibility

Default visibility depends on the enviroment (see chosen log writer for more information), and in most cases is setup through the following environment variables:

LOG_LEVEL

(defaults to notice) Lowest log level from which (upwards) all logs will be exposed.

LOG_DEBUG

Eventual list of namespaces to expose at levels below LOG_LEVEL threshold

List is comma separated as e.g. foo,-foo:bar (expose all foo but not foo:bar).

It follows convention configured within debug. To ease eventual migration from debug, configuration fallbacks to DEBUG env var if LOG_DEBUG is not present.

Timestamps logging

When following env var is set writers are recommended to expose timestamps aside each log message

LOG_TIME

• rel (default) - Logs time elapsed since logger initialization
• abs - Logs absolute time in ISO 8601 format

Tests

$ npm test

Project cross-browser compatibility supported by:

Security contact information

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

---

Get professional support for d with a Tidelift subscription
_{Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.}

Changelog

6.3.0 (2021-10-06)

Features

• Ensure mutlitple package instances share same master logger (685ec84), closes #11