@restorecommerce/logger

Opinionated wrapper and configurator for the winston logging toolkit

Usage no npm install needed!

<script type="module">
  import restorecommerceLogger from 'https://cdn.skypack.dev/@restorecommerce/logger';
</script>

README

@restorecommerce/logger

VersionBuild StatusDependenciesCoverage Status

Opinionated wrapper and configurator for the winston logging toolkit.

The following transports are supported:

  • Elasticsearch transport using a local transformer function and ES data streams.
  • index template which is applied automatically.
  • Console (Winston built-in transport).
  • File (Winston built-in transport).

These transports can be added and configured with a corresponding property in the options hash:

{
  "loggerName": "somelogger",        // Optional name
  "sourcePointer": true,             // Whether the source file and line where the log statement was issued should be logged [default: `false`]
  "esTransformer": function()  //
  "console": {
    "handleExceptions": false,
    "level": "silly",
    "colorize": true,
    "prettyPrint": true
  },
  "file": {
    ...
  },
  "elasticsearch": {
    ...
  }
}

The logger returns a Winston logger instance which has methods that correspond to the following levels:

  • silly
  • verbose
  • debug
  • info
  • warn
  • error
  • log (generic)

In addition there is a generic log() function.

Features

  • Source pointer logging -- show the source code file and line where the log statement was issued.
  • Implicit Request ID logging based on cls-rtracer.
  • Logger AsyncLocalStorage logger context to log implicit context information.
  • Supports local transformer function for the fields.

An example how to use the AsyncLocalStorage logger context can be found here.

Console logger

A custom format is defined that outputs the rid (request-id) if it is set and the contents of the AsyncLocalStorage context.

Elastichsearch logger

The following changes and transformations are applied to log messages:

  • Adds a @timestamp field with the current date/ time
  • Adds a host property with the current host name
  • Adds a rid request-id
  • Grabs all key/ values from the the current AsyncLocalStorage and merges them to the logged message

This module also comes with a suitable index pattern that can be imported in Kibana.

Usage

Instantiation

let logger = createLogger(opts);

Logging

Logging in general:

logger.<level>('Textual message');

// or

logger.log(<level>, 'Textual message');

The parameters for the log statements are built like this:

logger.info('Textual message');

// or

logger.info({ key: 'value' });

// or

logger.info('Textual message', { key: 'value' });

No other variants are supported.

See test.ts and the Winston documentation.