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

3.1 KiB Raw Blame History