@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

- [x] Basic logging
- [x] Allows for formatter extensions
- [x] Allows for transport extensions
- [x] Console transport creator
- [x] File transport creator
- [x] FluentD transport creator
- [x] Fluent transport security configuration
- [x] Fluent transport ID tagger

Installation

Install it via npm or yarn:

``sh
npm i @mcf/logger


or


yarn add @mcf/logger
`

Usage

$3

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

$3

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

`js
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');
`

$3

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

`js
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:

`xml

@type forward
bind 0.0.0.0
port 24224


*.>
@type stdout

`

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 |

$3

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()] |

$3

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 || os.hostname() || 'unknown' |
| 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.

$3

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 |

$3

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 |

$3

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:

`bash
yarn;
`

To run the usage example, set up FluentD first:

`bash
yarn svc:fluent;
`

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

`bash
yarn demo-usage;
`

To stop FluentD, run:

`bash
yarn svc:fluent:stop;
`

Changelog

$3


#### 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`)

$3

#### 0.1.0
Initial release with:
- Basic logging
- Allows for formatter extensions
- Allows for transport extensions
- FluentD transport creator
- Console transport creator