Skip to main content

@versionzero/logger

A simple yet powerful logging and tracing utility for Node.js with extensible record transforms and outputs.

Pairs well with @versionzero/module-manager.

Installation​

npm install @versionzero/logger

Basic Usage​

// ESM import
import { Logger } from '@versionzero/logger';

// Create a logger instance
const logger = new Logger('demo', {level: 'debug'});

// Log messages at different severity levels
logger.debug('Welcome!  have some detailed debug information');
logger.info('Hello, world!');
logger.notice('kind of a big deal')
logger.warn('warning message');
logger.error('Failed to do a thing', new Error('Connection to reality lost'));
logger.fatal(new Error('System has gone completely sideways'), {'guru-meditation': '0xDEADBEEF'});

// Log with data 
logger.info({ user: 'john', action: 'login' }, 'User logged in');

// Create a child logger that provides additional context to log with all records
const serviceLogger = logger.child('user-service', {context: {userServiceVersion: '1.2.1'}});
serviceLogger.debug({ user: 'bob', email: 'bob@example.com' }, 'service invoked');

The default "human-friendly" output mode will display something like this:

logger console output snapshot

whereas in json output mode, it can be sent for analysis by downstream observability tools:

logger console output snapshot


// You can create a child tracer logger that logs telemetry and transparently propagates trace context:
const txnLogger = serviceLogger.tracer('get-user');
const user = await txnLogger.run(async () => getUser());
txnLogger.info('got user', {user})
// Shorthand version
const user = await serviceLogger.trace('get-user', async () => getUser());

// You can also automatically instrument class methods with tracers to avoid having to wrap calls:
logger.instrument(userService);
const user = await userService.getUser();

Features​

  • Severity levels and filtering based on syslog standards
  • Hierarchical loggers with context inheritance
  • Extensible set of output handlers; default set supports console output (either pretty or json) and syslog (udp or tcp)
  • Extensible log record transform pipeline (can add processing for your own custom types)
  • Tracing with W3C/OpenTelemetry-compatible trace/span logging

Requirements​

  • ESM Modules
  • Node 20.9.0+

License​

This project is licensed under the MIT License -- see the LICENSE file for details.