winston-cfg

A simple utility that enables winston configuration via node-config

Usage

A brief introduction to winston internals

For most common use cases, there are three things that one needs to configure with winston:

1. transports: the destination(s) for the logs. Winston provides a few out of the box. Transports with external dependencies, with external dependencies are supported as 3rd party modules. Depending on the actual transport, some have pretty involved configuration.
2. loggers: an ability to segment logging capability, for example by application layer (app, http, db etc). Each logger can have multiple transports - either the global or a custom set.
3. default logger: winston instantiate a default logger that is configured with a 'Console' transport and set to 'info' level. This can be configured in exactly the same manner as any logger.

                 +-------------------------------------------+
                 |            winston configuration          |
+-------------+  |                                           |
| APPLICATION    |       +----------+                        |
|             |  |  +--> | Default  +--+                     |
|             |  |  |    +----------+  |                     |
| +---------+ |  |  |    +----------+  |   +-------------+   |
| | Layer 1 +----------> | Logger 1 +-+--> | Transport A +--------->
| +---------+ |  |       +----------+ |    +-------------+   |
|     ...     |  |                    |                      |
| +---------+ |  |       +----------+ +--> +-------------+   |
| | Layer N +----------> | Logger 1 +----> | Transport B +--------->
| +---------+ |  |       +----------+      +-------------+   |
+-------------+  |                                           |
                 |                                           |
                 +-------------------------------------------+

Simple Configuraton

Please see the interface definition in src/index.ts:Config for details on valid config settings.

And node-config for use of the config module.

// in config/defaults.json
{
  "winston": {
    "level": "info",
    "transports": [{
      "type": "Console"
    }]
  }
}

const log = require('winston-cfg').winstonCfg();

import { winstonCfg } from 'winston-cfg';
const log = winstongCfg();

Advanced Configuration

transportMap

Since transports may be external modules, winston expects to be provided instances of transports associated with a logger - global or custom.

We are however attempting to expose only the config capability. As a compromise, winston-cfg adds a 'type' property to the config. The application also has to instantiate a transportMap, which allows the winston-cfg to create appropriate transports before instantiating loggers.

By default, winston-core supports four transports: Console, File, Http & Memory. Additionally, 3rd-party transports extend support for other storage mechanisms.

Config file

Please see the interface definition in src/index.ts:Config for details on valid config settings.

And node-config for use of the config module.

{
  "winston": {
    "level": "info",
    "transports": [
      {
        "type": "Console"
      },
      {
        "type": "File",
        "filename": "./winston.log"
      },
      {
        "type": "CouchDB",
        // ... CouchDb Config.
      }
    ],
    "loggers": [{
      "id": "app",
      "level": "info",
      "transports": [{
        "type": "SimpleDB",
        // ...
      }],
    }, {
      "id": "http"
    }]
  }
}

TypeScript boilerplate

// do this in your application startup

import { winstonCfg } from 'winston-cfg';

// import custom transports
import { Couchdb as CouchDB } from 'winston-couchdb';
import { SimpleDB } from 'winston-simpledb';

// prepare a transport map for initialization
const transportMap = {
  'CouchDB': CouchDB,
  'SimpleDB': SimpleDB
};

// read config and initialize winston appropriately.
// See [node-config](https://github.com/lorenwest/node-config) for details.
const winston = winstonCfg(transportMap);

// get handles to individual loggers
const log = winston; // default logger
const app_log = winston.loggers.get('app');
const http_log = winston.loggers.get('http');

// use log, app_log & http_log as needed.

JavaScript boilerplate

const logger = 'winston-cfg';

// import custom transports
const CouchDB = require('winston-couchdb').CouchDb;
const SimpleDB = require('winston-simpledb').SimpleDB;

// prepare a transport map for initialization
const transportMap = {
  'CouchDB': CouchDB,
  'SimpleDB': SimpleDB
};

// read config and initialize winston appropriately.
// See [node-config](https://github.com/lorenwest/node-config) for details.
const winston = winstonCfg(transportMap);

// get handles to individual loggers
const log = winston; // default logger
const app_log = winston.loggers.get('app');
const http_log = winston.loggers.get('http');

// use log, app_log & http_log as needed.

License

Apache 2.0

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Support

Bugs, PRs, comments, suggestions are all welcomed!