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.
- [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
Install it via npm
or yarn
:
npm i @mcf/logger
# or
yarn add @mcf/logger
import {createConsoleTransport, createFluentTransport, createLogger} from '@mcf/logger';
// or
const {createConsoleTransport, createFluentTransport, createLogger} = require('@mcf/logger');
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');
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.
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 |
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()] |
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.
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
|
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 |
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 |
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;
Added in stream creator for Morgan (see .createMorganStream
)
Added more:
- Fluent transport security configuration (
.security
) - Fluent transport ID tagger (
.tag
) - Fluent transport TLS support (
.tls
and.tlsOptions
)
Initial release with:
- Basic logging
- Allows for formatter extensions
- Allows for transport extensions
- FluentD transport creator
- Console transport creator