andreasgrip / winston-sugar

Syntactical sugar on top of winston, configure winston will be easy using .json configurations file.

winston-sugar

Syntactical sugar on top of winston, configuring winston will be easy using .json configuration file.

Special thanks to all of winston team for the great logger.

Installation

Use npm command - npm i winston-sugar

winston-sugar will create a folder name config if not exist and add winston.json file template.

How to use it?

TL;DR Add the following lines, then continue use console.log as usual. const winstonLoader = require('winston-sugar'); winstonLoader.config('./config/winston.json'); const log = winstonLoader.getLogger(path.basename(process.argv[1], '.js')); winstonLoader.replaceConsole(log);

Full version

• Build your .json configurations file (rich example here-under).
• Require winston-sugar to get a class WinstonLoader instance.
• Load your winston logger configurations by passing the .json path to the config function.
• Get your winston logger by calling getLogger function, you can add category as string parameter if you need to have a child logger for a specific module.
• If you already have alot of console.log, console.error etc. in your code you can use winstonLoader.replaceConsole(log) to move them to winston instead;

note: you need to call config only one time from the entry point of your application.

• After that your can only do like this:

const logger = require('winston-sugar').getLogger('app');

example:

// Import winson-sugar when you need to have a winston instance
const winstonLoader = require('winston-sugar');

// This should be called in the application entry point only.
winstonLoader.config('../config/winston.json');

// Get winston logger
const log = winstonLoader.getLogger('app');

// Enjoy and log using winston
log.info("It's me winson-sugar :) "); 

Dependances

[email protected]

Build your .json winston configurations file

The .json configuration schema has 7 main parameters:

• level - (optional) Including the main logging level value (info,debug,warn ...etc.).

  ex. "level": "info" - Also it's the default value in winston-sugar

• levels - (optional) Including 2 child parameters (values & colors) if you need to customize your levels along with colors.

ex. Customize logger levels and it's clolors

"levels":{
     "values": {
       "trace": 6,
       "debug": 5,
       "info": 4,
       "warn": 3,
       "error": 2,
       "fatal": 1,
       "mark": 0
     },
     "colors": {
       "trace": "blue",
       "debug": "cyan",
       "info": "green",
       "warn": "yellow",
       "error": "red",
       "fatal": "magenta",
       "mark": "grey"
     }
   }

• silent - (optional) Use silent if you need to stop the winston logger by change it's value to true

  ex. "silent": false - Also it's the default value in winston-sugar

• exitOnError - (optional) Use exitOnError if you need to stop the winston when error occurred by change it's value to true

  "exitOnError": false - Also it's the default value in winston-sugar

• format - (mandatory) Array of winston.format functions, just put the exact function name without (), also you can add it's options as the following example. (please check winston.format from winston format section).

Extra Feature: Specially for winston.printf format function, I created a special syntax using templates, template is a callback function defined as string parameter, this function will be passed to winston.printf function in the runtime.

ex. Adding two winston.format functions, winston-sugar will combine all format functions on behalf of you :)

"format": [
    {
      "type": "timestamp",  
      "options": {
        "format": "YYYY-MM-DDThh:mm:ss.SSS"
      }
    },
    {
      "type": "printf", 
      "options": {
        "template": "custom" // the name of the custom template.
      }
    }
  ]

• transports - (mandatory) Array of winston.transports functions, just put the exact transport name, also you can add it's options as the following example. (please check winston.transports from winston transports section).

Extra Feature: Now you can restrict your transport for a specific levels using filters, I created a special syntax using templates, let's say you have 2 winston.transports.File you can configure the first to log info messages only, and the last for error and fatal.

Also using the new introduced env parameter, you can easily configure each transport to be run only for a specific environment. for this option winston-sugar will read define the application running environment from NODE_ENV global parameter.

ex. Adding 3 types of transports, one is type of Console for development, and the rest of type File for production.

"transports": [
    {
      "type": "Console",
      "name": "dev-logger",
      "env": "development",
      "options": {
        "stderrLevels ": [
          "fatal",
          "error"
        ],
        "consoleWarnLevels": [
          "debug",
          "warn"
        ],
        "handleExceptions": true,
        "format": [ // Override the deafult logging format.
          {
            "type": "printf",
            "options": {
              "template": "custom-colored" // the name of the custom template.
            }
          }
        ]
      }
    },
    {
      "type": "File",
      "name": "info-logger",
      "env": "production",
      "options": {
        "filename": "log/app.log",
        "maxsize": "100m",
        "maxFiles": 3,
        "tailable": true,
        "maxRetries": 3,
        "zippedArchive": true,
        "handleExceptions": true,
        "filters": [ // Override the logging level.
          "info",    // log level info and mark only.
          "mark"     
        ]
      }
    },
    {
      "type": "File",
      "name": "error-logger",
      "env": "production",
      "options": {
        "filename": "log/fatal.log",
        "maxsize": "100m",
        "maxFiles": 3,
        "tailable": true,
        "maxRetries": 3,
        "zippedArchive": true,
        "handleExceptions": true,
        "filters": [  // Override the logging level.
          "error",    // log level error and fatal only.
          "fatal"
        ]
      }
    }
  ]

• printf - (mandatory) Only if you are using printf as a type of winston.format function, you can easy defined you logging template as callback function.

Warning: Check the syntax of your callback function before converting it to a string format. wrong syntax will throw an error in the runtime.

ex. Three callback funcation templates

"printf": {
    "templates": {
      "custom": "(({level, message, category, timestamp})=> { return `[${timestamp}] [${level}] ${(category)?category:'winston'} - ${message}`;})",
      "custom-colored": "(({level, message, category, timestamp})=> { return winston.format.colorize({all:true}).colorize(level,`[${timestamp}] [${level.toUpperCase()}] ${(category)?category:'winston'}`) + ` - ${message}`;})",
      "custom-all": "((info) => {let message = `${new Date(Date.now()).toUTCString()} | ${info.level.toUpperCase()} | ${info.message} | `; message = info.obj ? message + `data:${JSON.stringify(info.obj)} | ` : message; message = this.log_data ? message + `log_data:${JSON.stringify(this.log_data)} | ` : message; return message;})"
    }
  }

Configurations .json file template

• Please check the winston.json under config directory.

Licenses

MIT License

Copyright (c) 2020 Mohamed El Sayad (Anubis)