{"id":11248,"library":"log","title":"Universal Pluggable Logging Utility","description":"The `log` package provides a universal and pluggable logging utility designed for JavaScript applications, currently stable at version 6.3.2. It focuses on being configurable, environment, and presentation agnostic, differentiating itself by not handling output directly but emitting events for external 'writers' (e.g., `log-node` for Node.js environments). Releases are made as needed, with several maintenance and minor feature updates occurring within the last few years. Key features include syslog-compatible log levels (debug, info, notice, warning, error), `debug`-style namespacing for granular control, and support for printf-like message formatting with various placeholders (e.g., `%s`, `%d`, `%j`, `%o`). This design allows developers to write application logs once and integrate different output mechanisms without changing core logging logic. It does not expose `critical`, `alert`, or `emergency` levels, expecting these to be handled as typical exceptions. A crucial differentiator is its modular approach, requiring an explicit 'writer' package to actually emit log messages, making it highly adaptable to various runtime environments and output formats.","status":"active","version":"6.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/medikoo/log","tags":["javascript","log","logger","debug","bunyan","winston"],"install":[{"cmd":"npm install log","lang":"bash","label":"npm"},{"cmd":"yarn add log","lang":"bash","label":"yarn"},{"cmd":"pnpm add log","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for logging output in Node.js environments. The `log` package itself only emits events, and needs a concrete writer to display or store logs. Other writers exist for different environments.","package":"log-node","optional":false}],"imports":[{"note":"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.","wrong":"const log = require('log');","symbol":"log","correct":"import log from 'log';"},{"note":"The `get` method for creating namespaced loggers is an instance method of the default `log` object, not a direct named export.","wrong":"import { get } from 'log'; // Incorrectly assumes `get` is a named export","symbol":"log.get","correct":"const namespaceLog = log.get('my-namespace');"},{"note":"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.","wrong":"require('log-node'); // In ESM context, this should be an import statement","symbol":"log-node initialization","correct":"import 'log-node';"}],"quickstart":{"code":"import log from 'log';\nimport 'log-node'; // Initialize the Node.js writer for log output\n\n// Default logger (writes at 'info' level by default)\nlog.info(\"Application started: %s\", new Date().toISOString());\n\n// Get a namespaced logger (similar to 'debug' library style)\nconst myLibLog = log.get('my-lib');\nmyLibLog.info(\"Initializing 'my-lib' module with config: %j\", { debug: true, port: 3000 });\n\n// Namespaces can be nested\nconst myLibFuncLog = myLibLog.get('func');\nmyLibFuncLog.debug(\"Executing critical function 'processData' for ID: %d\", 12345);\n\n// Log an 'error' level message\nmyLibFuncLog.error(\"Failed to process data due to an unexpected error. Details: %s\", \"Invalid input\");\n\n// Dynamically disable/enable logging for a specific level\nconst { restore } = myLibFuncLog.debug.disable();\nmyLibFuncLog.debug(\"This debug message should not be logged.\");\nrestore(); // Restore previous visibility state\nmyLibFuncLog.debug(\"This debug message should now be logged.\");\n","lang":"javascript","description":"Demonstrates initializing the log system with `log-node`, creating default and namespaced loggers, logging at different levels, and dynamic enabling/disabling of log output."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=6.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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')();`).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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')();`.","cause":"The `log` package requires a separate 'writer' module to process and output log events. It does not write to the console by default.","error":"No log messages appear in the console/output."},{"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.","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).","error":"My 'error' messages are being treated as low severity, or 'debug' messages are high severity."}],"ecosystem":"npm"}