@opuscapita/logger

OpusCapita common logging. Wiki 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).

Versions

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, // Deprecated with no replacement. This states the log level used when using .log() method.
    minLogLevel : Logger.LogLevel.Info, // Deprecated - use configuration instead. Logs less severe won't be logged.
    outputStreams : { // Output can be streamed to stdout/stderr (default) or any other writeable stream
        [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 : { // Optional context used with every log message
        name: null, // Indicate current logger instance
        serviceName : Logger.serviceName, // Deprecated - use 'name' instead
        serviceInstanceId : 0, // Deprecated - no replacement.
        correlationId : null, // Optional. Client request ID.
        userId : null, // Optional. User ID.
        requestUri : null // Optional. Request URI.
    }
}

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 - you should avoid using logger.log and instead specify log severity level
• minLogLevel - is fine controlled using configuration (different parts of service can be using different verbosity)
• 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

Configuration

• You should create a file logger.json in your project directory - it would be used on production.
• You can have file etc/logger.json that takes precedence before logger.json if found.
• You can set environment variable LOGGER_CONFIG_FILE 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.

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.