esm-logging

A quasi-port of the Python standard library logging module to ECMAScript. Browser-compatible, zero dependencies.

Why?

Logging is important. It is important for debugging purposes, leading to faster and more resilient development, for traceability leading to better security. Most logging libraries I've discovered didn't satisfy me, introduced weird concepts and all in all just weren't great. Other programming language ecosystems offer way nicer logging facilities. Take Rust for example, or... Python! Python has PEP, giving it a very structured approach towards implementing new features and that's also how its logging facilities came to be (PEP 282). Python's logging facilities are implemented by the logging module, which is part of the standard library and has been since 2002. It was originally authored by Vinay Sajip.

Installation

npm install @administratrix/esm-logging

Quick start

import * as logging from '@administratrix/esm-logging';

// one-shot configuration: sets up a console handler on the root logger
logging.config.basicConfig({ level: logging.log_level.INFO });

// create a logger for this module
const logger = logging.manager.MANAGER.getLogger('myapp');

logger.info('Application started');
logger.warning('Something looks off');
logger.error('Something went wrong');

Concepts

The logging system is built around four core components:

• Loggers expose the interface that application code uses directly.
• Handlers send log records to the appropriate destination (console, stderr, custom writable streams).
• Formatters control the layout of log records in the final output.
• Filters provide fine-grained control over which records to output.

Loggers are organized in a dot-separated hierarchy. A logger named app.db is a child of the logger named app. Log records propagate up the hierarchy, so a handler attached to app will also receive records from app.db.

Log levels

Constant	Value	Purpose
CRITICAL	50	A serious error, the program may not continue
ERROR	40	An error that prevented some operation
WARNING	30	Something unexpected, but the software still works
INFO	20	Confirmation that things work as expected
DEBUG	10	Detailed diagnostic information
NOTSET	0	All messages are processed

Documentation

See docs/ for the full user guide and docs/logging-cookbook.md for recipes and patterns.

API reference can be generated with TypeDoc:

npm run build/doc

Roadmap

• quasi-port of the logging module with minimal adaptation
• add documentation
• add support for asynchronous calls
• implement Open Cybersecurity Schema Framework (OCSF) formatter
• implement browser local storage handler as a replacement for file handler

License

UNLICENSED