Unified logging component for OpusCapita Andariel platform.

Downloads in past


2.0.28 months ago4 years agoMinified + gzip package size for @opuscapita/logger in KB


This module provides simple common logging. For further details of how to use this module, please have a look at the wiki.
Currently this module is released manually
Known issues
Versions 1.3.x had an issue where logging logic was reversed (more severe logs not logged while less severe logged).
See https://github.com/OpusCapita/logger/releases

Minimum setup

Install logger to your project:
npm install @opuscapita/logger

After that you can directly use the logger component.
const Logger = require('@opuscapita/logger');

const logger = new Logger({context:{name:"My preferably unique logger name"});
logger.info('Hello world!');

logger.trace('Very detailed logs', {details: 'Variable data'});
logger.debug('Detailed logs, normally off', {details: 'Variable data'});
logger.info('Information', {details: 'This is normally logged on production - try to use it only when needed'});
logger.warn('Something wrong but handled', {error: errorThrown, details: 'It is something that is worth looking into but not an issue that require immediate work'});
logger.error('Something bad happened - someone MUST look at it', {details: 'There is a transaction broken or something similar - customer is impacted and someone needs to solve the issue'});
logger.fatal('System is down', {details: 'Use it is major outage happened (and likely system is not reliable)'});

Default configuration

The default configuration object provides hints about what the module's standard behavior is like and which configuration options are available. For further details about the API, please have a look at the wiki.
    defaultLogLevel : Logger.LogLevel.Info,
    minLogLevel : Logger.LogLevel.Info,
    outputStreams : {
        [Logger.LogLevel.Trace] : process.stdout,
        [Logger.LogLevel.Debug] : process.stdout,
        [Logger.LogLevel.Info] : process.stdout,
        [Logger.LogLevel.Warning] : process.stdout,
        [Logger.LogLevel.Error] : process.stderr,
        [Logger.LogLevel.Fatal] : process.stderr
    context : {
        name: null,
        serviceName : Logger.serviceName,
        serviceInstanceId : 0,
        correlationId : null,
        userId : null,
        requestUri : null

Note that some settings would become obsolete in the future - logging configuration should be set by the environment, not by code. And the environment is preferably created by a code ;)
  • defaultLogLevel and minLogLevel should dynamically change (user will be able to change configuration during runtime in the future)
  • outputStreams could become more abstract - one can print to something else than a terminal/file but the concept generally is not planned to change
  • context is going to move into local storage instead - logger shouldn't be contextified, session (call chain) should be
  • You should create a file logger.json in your project directory.
  • You can have file etc/logger.json that takes precedence before logger.json if found.
  • You can set environment variable LOGGERCONFIGFILE to a path that takes precedence before the two above.

The first file found - it would be the only used and monitored for changes.
See https://github.com/OpusCapita/logger/wiki/Configuration

An example self-explaining logger.json with explanation

  "serviceName": {
    "my service name": "Debug"
  "name": {
    "my preferably unique logger name": "Trace",
    "some logger that I am not interested in": "Warning"
  "requestUri": {
    "/api/health/check": "Fatal",
    "/api/buggy/endpoint": "Trace"
  "userId": {
    "superduperadmin": "Trace"
  "default": {
    "level": "Info",
    "formatter": ""
The JSON file does NOT support comments by its specification :(
The "formatter" field is optional. When not found (or empty string) then JSON formatter is used. When testing locally you might consider other options that are ci, ci-wide, terminal, color and color-1line.
Image with example output
Output contains standard fields and some extra specific to OpusCapita backend:
  • timestamp (custom formatters showing only hour down to milliseconds skipping date due to assumption that you run local tests lasting less than a day)
  • log level (can be additionally used for output color)
  • our services are usually REST servers thus
- correlation-id - an unique identified for the system's REST user request that should be passed with subsequent calls - URI path of the REST request
  • log message
  • optional log payload
- should be a single object
- every object's key is added to the log object output for JSON output formatter
- for custom formatters payload is printed after the message
- multiple values can be passed just like with console but preferred way is a single object
- due to technical reasons  when multiple parameters are passed, those are stringified and appended to the log message rather
Migration between versions

1.0.14 to 1.0.15

Module 'correlation-id' is used and it requires node 12.17.0 or newer for node AsyncLocalStorage. Update node to 12.17.0 or newer.

1.x.x to 2.x.x

DummyLogger and VerboseLogger were removed. Create a normal logger instance instead like this: new Logger({level: Logger.LogLevel.Exception) or new Logger({level: Logger.LogLevel.Trace}) or even if you must use hardcoded values like -9999 (very silent), 999999 Very verbose, +Infinity, -Infinity, ...
debugMode was removed, .setDebugMode function removed as well. Remove all references. Do not use - instead just increase log level if needed.
Support for callback as last parameter to log calls was removed (previously deprecated as unsafe). Do not use any longer. If used callbacks are treated as extra arguments to log.
Configuration parameters minLogLevel and defaultLogLevel are deprecated and no longer used. If found in the config file - would be still used for backward compatibility. Rename them to level If passed in constructor they would be ignored.
Support for custom output streams might be removed in the future (replaced with different implementation). If used - let me know. Otherwise I would try to remove this in version 3.x
Custom log levels are deprecated. Stick with defaults and commonly used levels and you are fine. Change all custom levels to one of the default.