@sitespeed.io/log

A small, zero-dependency console logger used by sitespeed.io and related projects. It writes timestamped, level-aware messages to console, supports printf-style placeholders, and is configured once for the whole process.

Install

npm install @sitespeed.io/log

Requires Node.js 22 or later. ESM only.

Usage

import { configureLog, getLogger } from '@sitespeed.io/log';

configureLog({ verbose: 1 });

const log = getLogger('my-module');

log.info('Starting up');
log.debug('Using config %j', { port: 3000 });
log.error('Failed to load %s', 'plugin.js', new Error('boom'));

Output:

[2025-05-16 14:22:01] INFO: Starting up
[2025-05-16 14:22:01] DEBUG: [my-module] Using config {
  "port": 3000
}
[2025-05-16 14:22:01] ERROR: [my-module] Failed to load plugin.js Error: boom
    at ...

At info (the default) the logger name is omitted. At debug and below it is included, since extra noise is usually wanted there.

Log levels

Lowest number = most critical. Setting a level enables that level and everything more critical:

Level	Number	console method
none	0	(disabled)
critical	1	error
error	2	error
warning	3	warn
info	4	info (default)
debug	5	debug
verbose	6	log
trace	7	trace

Configuration

configureLog({
  level: 'debug',  // exact level by name (takes precedence)
  verbose: 0,      // 0 = info, 1 = debug, 2 = verbose, 3 = trace
  silent: false    // true disables all logging
});

Precedence: silent > level > verbose. Call configureLog() once near the start of your process; configuration is global.

Logger API

getLogger(name) returns a Logger. Names show up in the output when the level is debug or below.

const log = getLogger('my-module');

log.critical(message, ...args);
log.error(message, ...args);
log.warning(message, ...args);   // log.warn is an alias
log.info(message, ...args);
log.debug(message, ...args);
log.verbose(message, ...args);
log.trace(message, ...args);

if (log.isEnabledFor('debug')) {
  log.debug('Expensive: %j', computeStuff());
}

Message placeholders

Placeholders are replaced left-to-right with the trailing arguments. Leftover arguments are appended.

Placeholder	Replaced with
%s	String(arg)
%d	String(Number(arg))
%j	JSON.stringify(arg, null, 2)
%O	Pretty-printed object, or {name, message, stack} for Error
%?	Inline: String(arg), pretty JSON for objects, Error: …\n<stack> for Error

log.info('user=%s requests=%d', 'alice', 42);
log.error('Request failed: %?', err);

$ is not a special character — log.info('price $1') prints price $1 verbatim.

Advanced

Logger and the live loggerConfig object are exported for cases where you need to subclass or read the current level/format directly. Most users only need configureLog and getLogger.

License

Apache-2.0