@mcf/logger

Exposes a logger based on Winston. It includes formats and plugins for integration with the Morgan request logging library, and xray request distributed tracing library.

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
324Jun 11, 2021May 10, 2018Minified + gzip package size for @mcf/logger in KB

Readme

npm version

@mcf/logger

Exposes a logger based on Winston. It includes formats and plugins for integration with the Morgan request logging library, and Zipkin request distributed tracing library.

Scope

  • Basic logging
  • Allows for formatter extensions
  • Allows for transport extensions
  • Console transport creator
  • File transport creator
  • FluentD transport creator
  • Fluent transport security configuration
  • Fluent transport ID tagger

Installation

Install it via npm or yarn:

npm i @mcf/logger
# or
yarn add @mcf/logger

Usage

Requiring

import {createConsoleTransport, createFluentTransport, createLogger} from '@mcf/logger';
// or
const {createConsoleTransport, createFluentTransport, createLogger} = require('@mcf/logger');

Basic

By default, the logger already logs to the console and no configuration is needed. This should suffice for basic apps.

const basicLogger = createLogger();
basicLogger.silly('a silly hi');
basicLogger.debug('a debug hi');
basicLogger.http('a http hi');
basicLogger.info('a info hi');
basicLogger.warn('a warn hi');
basicLogger.error('a error hi');

FluentD

We use fluent for our centralised logs collector. To initialise the transport, create the logger as such:

const fluentLogger = createLogger({
  additionalTransports: [
    createFluentTransport({
      host: 'localhost',
      port: 44224,
      timeout: 2.0,
      requireAckResponse: false,
    }),
  ],
  // optional message transformation, depends on your elasticsearch setup
  formatters: [
    (info) => {
      const messageIsObject = typeof info.message === 'object';
      return {
        ...info,
        message: messageIsObject ? 'meta' : info.message,
        meta: messageIsObject ? info.message : undefined,
      };
    },
  ],
});

fluentLogger.info('hello world!');

The following fluent.conf should get you up and running:

<source>
  @type forward
  bind 0.0.0.0
  port 24224
</source>

<match **.*>
  @type stdout
</match>

See the usage example for more examples of creating plaintext/encrypted loggers.

Documentation

The library exposes the following methods:

Method Description
.createLogger Creates the logger object which can be used
.createFluentTransport Creates a FluentD compatible transport
.createConsoleTransport Creates a Console transport
.createFileTransport Creates a File transport
.createMorganStream Creates an object consumable by Morgan

.createLogger(:options)

This function accepts a configuration object as the parameter where the keys are documented as follows:

Key Description Default
additionalTransports Winston transports to be added on (no overriding of the default Console transport) []
formatters Winston formatters created via winston.format(...)() []
level Default level (ENUM { "error", "warn", "info", "http", "debug", "silly" }) "silly"
namespace Give a name to your logger) give-me-a-name
silent Set to true to turn off logging false
transports Winston transports [winston.transports.Console()]

.createFluentTransport(:options)

This function accepts a configuration object as the parameter where the keys are documented as follows:

Key Description Default
host FluentD service hostname "localhost"
port FluentD service port 24224
requireAckResponse Specifies whether we should connect via TCP (true) or UDP (false) false
security A security object with .clientHostname : string and .sharedKey : string properties undefined
tag Tag for the logs `process.env.HOSTNAME
tls Specifies if we should use TLS true
tlsOptions Specifies an options object for the TLS connection which has a .ca property undefined
timeout Timeout for a push 3.0

This is referenced from the fluent-logger library.

.createConsoleTransport(:options)

This function accepts a configuration object as the parameter where the keys are documented as follows:

Key Description Default
format Winston formatters created via winston.format(...)() Combination of colorize and custom printf displaying namespace, timestamp, level and message

.createFileTransport(:options)

This function accepts a configuration object as the parameter where the keys are documented as follows:

Key Description Default
format Winston formatters created via winston.format(...)() Custom printf displaying namespace, timestamp, level and message
filename Filename to output undefined

.createMorganStream(:options)

This function returns an object that can be used by Morgan to specify a write stream.

The properties for the :options object are:

Key Description Default
logLevel The desire level of logs to use for request logs by Morgan "silly"
logger The logger instance to be used undefined

Examples

Confirm all dependencies have been installed:

yarn;

To run the usage example, set up FluentD first:

yarn svc:fluent;

In another terminal, run the usage application which will pipe to the FluentD instance:

yarn demo-usage;

To stop FluentD, run:

yarn svc:fluent:stop;

Changelog

0.2.x

0.2.1

Added in stream creator for Morgan (see .createMorganStream)

0.2.0

Added more:

  • Fluent transport security configuration (.security)
  • Fluent transport ID tagger (.tag)
  • Fluent transport TLS support (.tls and .tlsOptions)

    0.1.x

    0.1.0

    Initial release with:
  • Basic logging
  • Allows for formatter extensions
  • Allows for transport extensions
  • FluentD transport creator
  • Console transport creator

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.