docs: add user guide, cookbook, and rewrite README

2026-03-14 04:33:53 +01:00

9.7 KiB

Raw Blame History

esm-logging user guide

This guide covers the @administratrix/esm-logging library, a quasi-port of Python's logging module for ECMAScript. It targets browser environments and provides hierarchical, configurable logging with formatters, handlers, and filters.

Basic usage
Loggers
Handlers
Formatters
Filters
Configuration
Log record attributes

Basic usage

The simplest way to start logging is with basicConfig:

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

logging.config.basicConfig({
    level: logging.log_level.DEBUG,
    format: '%(levelname)s:%(name)s:%(message)s',
});

const logger = logging.manager.MANAGER.getLogger('myapp');
logger.info('Hello, world');
// output: INFO:myapp:Hello, world

basicConfig creates a StreamHandler writing to stderr (via console.error) and attaches it to the root logger. It is a one-shot function: calling it again has no effect unless you pass force: true.

Loggers

Loggers are the entry point for emitting log records. They are organized in a dot-separated hierarchy managed by a singleton Manager.

Creating loggers

const logger = logging.manager.MANAGER.getLogger('myapp');
const childLogger = logging.manager.MANAGER.getLogger('myapp.db');

Calling getLogger with the same scope always returns the same logger instance. The hierarchy is established automatically: myapp.db is a child of myapp.

Setting levels

logger.setLevel(logging.log_level.WARNING);

A logger only processes messages at or above its effective level. The effective level is determined by walking up the parent chain until a logger with a non-zero level is found. The root logger defaults to WARNING.

Logging methods

Each level has a corresponding method:

logger.debug('Detailed diagnostic info');
logger.info('Things are working');
logger.warning('Something unexpected');
logger.error('An operation failed');
logger.critical('System is in trouble');

Propagation

By default, log records propagate up the hierarchy. A record emitted by myapp.db will be handled by handlers on myapp.db, then myapp, then the root logger. This means you typically only need to configure handlers on the root logger or on high-level loggers.

Checking if a level is enabled

if (logger.isEnabledFor(logging.log_level.DEBUG)) {
    logger.debug('Expensive computation: ' + computeDebugInfo());
}

This avoids the cost of building the message string when the level would be filtered out anyway.

Handlers

Handlers determine where log records go. A logger can have multiple handlers, and each handler can have its own level and formatter.

Available handlers

StreamHandler

Writes formatted output to a Writable stream. Defaults to stderr (via console.error).

import { StreamHandler } from '@administratrix/esm-logging/src/handler';
import { ConsoleWritable } from '@administratrix/esm-logging/src/helper/stream';

const handler = new StreamHandler(new ConsoleWritable());
logger.addHandler(handler);

ConsoleHandler

Maps log levels to the appropriate browser console method:

ERROR and CRITICAL use console.error
WARNING uses console.warn
DEBUG and INFO use console.log

import { ConsoleHandler } from '@administratrix/esm-logging/src/handler';

const handler = new ConsoleHandler();
handler.level = logging.log_level.DEBUG;
logger.addHandler(handler);

StderrHandler

Always writes to console.error, regardless of level. Useful when you want all output on stderr.

import { StderrHandler } from '@administratrix/esm-logging/src/handler';

const handler = new StderrHandler(logging.log_level.WARNING);
logger.addHandler(handler);

FileHandler

Not available in browser environments. Throws NotImplementedError on construction. Use ConsoleHandler or a storage-backed handler instead.

Handler methods

handler.level = logging.log_level.INFO;  // only handle INFO and above
handler.formatter = myFormatter;         // set a custom formatter
handler.close();                         // release resources

Custom handlers

Subclass Handler and implement emit(record):

import { Handler } from '@administratrix/esm-logging/src/handler';

class ArrayHandler extends Handler {
    constructor() {
        super();
        this.records = [];
    }

    emit(record) {
        this.records.push(this.format(record));
    }
}

Formatters

Formatters control how log records are rendered as strings. The default format is %(message)s (just the message). The basic format used by basicConfig is %(levelname)s:%(name)s:%(message)s.

Creating a formatter

import { Formatter } from '@administratrix/esm-logging/src/formatter';

const formatter = new Formatter({
    fmt: '%(asctime)s - %(levelname)s - %(name)s - %(message)s',
    datefmt: '%Y-%m-%d %H:%M:%S',
});

handler.formatter = formatter;

Format string placeholders

Formatters use %-style substitution. Available placeholders correspond to log record attributes:

%(name)s        Logger scope name
%(levelno)d     Numeric log level
%(levelname)s   Text log level (DEBUG, INFO, etc.)
%(message)s     The formatted message
%(asctime)s     Human-readable timestamp
%(created)f     Milliseconds since epoch (Date.now())

Date formatting

The datefmt option accepts strftime-style tokens:

Token	Meaning	Example
`%Y`	Four-digit year	2026
`%m`	Zero-padded month	03
`%d`	Zero-padded day	14
`%H`	Hour (24h)	09
`%M`	Minute	05
`%S`	Second	30

If datefmt is omitted, an ISO 8601-like format is used: 2026-03-14 09:05:30.123.

Filters

Filters provide fine-grained control over which records get processed. They can be attached to loggers or handlers.

Scope-based filtering

A Filter initialized with a scope name only allows records from that scope and its children:

import { Filter } from '@administratrix/esm-logging/src/filter';

const filter = new Filter('myapp.db');
handler.addFilter(filter);
// only records from 'myapp.db' and 'myapp.db.*' will pass

A filter initialized with an empty string allows all records.

Custom filters

Any object with a filter(record) method can be used:

handler.addFilter({
    filter(record) {
        return record.levelno >= logging.log_level.WARNING;
    }
});

Configuration

basicConfig

basicConfig is a convenience function for simple, one-shot configuration of the root logger:

logging.config.basicConfig({
    level: logging.log_level.DEBUG,
    format: '%(asctime)s %(levelname)s %(message)s',
    datefmt: '%Y-%m-%d %H:%M:%S',
});

Options

Option	Type	Description
`level`	`number`	Root logger level
`format`	`string`	Format string for the handler's formatter
`datefmt`	`string`	Date format string
`style`	`string`	Format style (`'%'` only, currently)
`handlers`	`Handler[]`	Pre-built handlers to attach
`stream`	`Writable`	Stream for the default StreamHandler
`force`	`boolean`	Remove existing handlers first

stream and handlers are mutually exclusive.

Manual configuration

For more control, configure loggers and handlers directly:

const root = logging.manager.MANAGER.root;
const handler = new ConsoleHandler();
handler.level = logging.log_level.DEBUG;
handler.formatter = new Formatter({
    fmt: '%(asctime)s [%(levelname)s] %(name)s: %(message)s',
});
root.addHandler(handler);
root.setLevel(logging.log_level.DEBUG);

Log record attributes

A LogRecord carries the following attributes:

Attribute	Type	Description
`scope`	`string`	Logger name that created the record
`name`	`string`	Same as `scope`
`levelno`	`number`	Numeric level (10, 20, 30, 40, 50)
`levelname`	`string`	Text level (`DEBUG`, `INFO`, etc.)
`msg`	`string`	The raw message template
`args`	`any[]`	Substitution arguments for `%s` in msg
`message`	`string`	The formatted message (set by formatter)
`created`	`number`	Milliseconds since Unix epoch
`asctime`	`string`	Formatted timestamp (set by formatter)

The getMessage() method on LogRecord performs %s argument substitution on msg using args.

Module structure

The library is organized into submodules, all re-exported from the main entry point:

Import path	Contents
`config`	`basicConfig()`
`filter`	`Filter`, `Filterer`
`formatter`	`Formatter`, `STYLES`, `DEFAULT_FORMATTER`
`handler`	`Handler`, `StreamHandler`, `ConsoleHandler`, `StderrHandler`, `FileHandler`
`log_level`	Level constants, `getLevelName()`, `checkLevel()`
`log_record`	`LogRecord`, factory functions
`logger`	`Logger`, `RootLogger`, `ROOT`
`manager`	`Manager`, `MANAGER`

9.7 KiB Raw Blame History