Universal Pluggable Logging Utility

Common errors

• No log messages appear in the console/output.

  cause The `log` package requires a separate 'writer' module to process and output log events. It does not write to the console by default.
  fix Install and initialize a writer package, such as `log-node`, at the entry point of your application. Example: `npm install log-node` then `import 'log-node';` or `require('log-node')();`.

• My 'error' messages are being treated as low severity, or 'debug' messages are high severity.

  cause In version 5.0.0, the numerical indexing of log levels was reversed to align with RFC 5424. `error` is now 0 (highest severity), and `debug` is 4 (lowest severity).
  fix Ensure your code, especially any custom writers or filters, is aware of the reversed level indexing if you are comparing levels by their numerical values. It's safer to use the named methods (e.g., `log.error()`, `log.debug()`) rather than relying on index values.

Warnings

• breaking The internal API for registering and accessing the master writer changed in v6.0.0. `lib/register-master` was removed in favor of `lib/get-master-writer`, and `lib/writer` was renamed to `lib/abstract-writer`.
  Fix: Review the migration guide if you were using custom writers directly manipulating the internal master writer registration. For most users, updating `log-node` or other specific writer packages should resolve this.
• breaking In v5.0.0, the internal level indexes were reversed to align with RFC 5424 syslog severity order. `error` now has index `0`, and `debug` has `4`. This means custom logic or writers that relied on the numerical index of levels will need to be updated.
  Fix: Adjust any custom code that directly compares or interprets log levels based on their numerical index. Rely on the named level methods (e.g., `log.error`, `log.debug`) rather than their underlying numerical values for future compatibility.
• gotcha The `log` package itself does not produce any output. It functions as an event emitter. To see logs in your console or other destinations, you *must* install and initialize a separate 'writer' package, such as `log-node` for Node.js environments.
  Fix: Install a suitable writer package (e.g., `npm install log-node`) and ensure it is initialized at your application's entry point (e.g., `import 'log-node';` or `require('log-node')();`).
• gotcha The `log` package intentionally does not expose `critical`, `alert`, or `emergency` syslog levels. These are deemed suitable for handling as typical JavaScript exceptions rather than log messages within application code.
  Fix: For conditions that would typically map to `critical`, `alert`, or `emergency` severity, use standard JavaScript error handling mechanisms (e.g., throwing and catching exceptions, process error handlers) instead of attempting to log them through this utility.

Install

• npm install log npm
• yarn add log yarn
• pnpm add log pnpm

Imports

• log
  wrong:

  const log = require('log');

  correct:

  import log from 'log';

  While `require('log')` is shown in older documentation, ESM `import` is the recommended modern approach for better static analysis and future compatibility. Both are currently supported in Node.js environments.
• log.get
  wrong:

  import { get } from 'log'; // Incorrectly assumes `get` is a named export

  correct:

  const namespaceLog = log.get('my-namespace');

  The `get` method for creating namespaced loggers is an instance method of the default `log` object, not a direct named export.
• log-node initialization
  wrong:

  require('log-node'); // In ESM context, this should be an import statement

  correct:

  import 'log-node';

  To initialize the Node.js log writer, `log-node` should be imported for its side effects, typically at the entry point of your application. No specific symbol is imported, as it registers itself globally.

Quickstart

Demonstrates initializing the log system with `log-node`, creating default and namespaced loggers, logging at different levels, and dynamic enabling/disabling of log output.

import log from 'log';
import 'log-node'; // Initialize the Node.js writer for log output

// Default logger (writes at 'info' level by default)
log.info("Application started: %s", new Date().toISOString());

// Get a namespaced logger (similar to 'debug' library style)
const myLibLog = log.get('my-lib');
myLibLog.info("Initializing 'my-lib' module with config: %j", { debug: true, port: 3000 });

// Namespaces can be nested
const myLibFuncLog = myLibLog.get('func');
myLibFuncLog.debug("Executing critical function 'processData' for ID: %d", 12345);

// Log an 'error' level message
myLibFuncLog.error("Failed to process data due to an unexpected error. Details: %s", "Invalid input");

// Dynamically disable/enable logging for a specific level
const { restore } = myLibFuncLog.debug.disable();
myLibFuncLog.debug("This debug message should not be logged.");
restore(); // Restore previous visibility state
myLibFuncLog.debug("This debug message should now be logged.");