winston-sugar is a syntactical sugar on top of winston, winston-sugar makes your winston configurations more easy by using a single .json configurations file.
Installation
Use npm command - npm i winston-sugar
winston-sugar will create a folder name config if not exist and generate winston.json file template, this .json file will me the single point of all of your configurations.
How to use it?
- Edit your json configurations file template.
- Require
winston-sugarto get a classWinstonLoaderinstance. - Load your
winston.Logger' configurations by passing the .json path to theconfig` function. - Get your
winston.Logger' instance by callinggetLogger()function, you can addcategory` as string parameter if you need to have a child logger for a specific module.
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
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
silentif you need to stop the winston logger by change it's value totrue
ex. "silent": false - Also it's the default value in winston-sugar
-
exitOnError - (optional) Use
exitOnErrorif you need to stop the winston when error occurred by change it's value totrue
"exitOnError": false - Also it's the default value in winston-sugar
-
format - (mandatory) Array of
winston.formatfunctions, just put the exact function name without (), also you can add it's options as the following example. (please checkwinston.formatfrom 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.transportsfunctions, just put the exact transport name, also you can add it's options as the following example. (please checkwinston.transportsfrom 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
printfas a type ofwinston.formatfunction, 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
- Once you installed
winston-sugarcheck thewinston.jsonfile underconfigdirectory, and change it based on your needs.
Licenses
MIT License
Copyright (c) 2020 Mohamed El Sayad
Top comments (0)