npm package: @opuscapita/logger
Description: Unified logging component for OpusCapita Andariel platform.
Latest version: 2.1.4

![](https://img.shields.io/bundlephobia/min/@opuscapita/logger)
![](https://img.shields.io/node/v/@opuscapita/logger)
![](https://img.shields.io/npm/types/@opuscapita/logger)

# @opuscapita/logger
OpusCapita common logging.
Wiki at the [wiki](https://github.com/OpusCapita/logger/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.

```JS
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](https://github.com/OpusCapita/logger/wiki).

```JS
{
    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

```JSON
{
  "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](LoggerFormatters.png)

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.*