winston@3

Looking forwinston@2.x documentation?

Motivation

Quick Start

Usage

constwinston=require('winston');constlogger=winston.createLogger({level:'info',format:winston.format.json(),defaultMeta:{service:'user-service'},transports:[//// - Write all logs with importance level of `error` or higher to `error.log`//   (i.e., error, fatal, but not other levels)//newwinston.transports.File({filename:'error.log',level:'error'}),//// - Write all logs with importance level of `info` or higher to `combined.log`//   (i.e., fatal, error, warn, and info, but not trace)//newwinston.transports.File({filename:'combined.log'}),],});//// If we're not in production then log to the `console` with the format:// `${info.level}: ${info.message} JSON.stringify({ ...rest }) `//if(process.env.NODE_ENV!=='production'){logger.add(newwinston.transports.Console({format:winston.format.simple(),}));}

Table of contents

Logging

constlevels={error:0,warn:1,info:2,http:3,verbose:4,debug:5,silly:6};

Creating your own Logger

constlogger=winston.createLogger({transports:[newwinston.transports.Console(),newwinston.transports.File({filename:'combined.log'})]});

//// Logging//logger.log({level:'info',message:'Hello distributed log files!'});logger.info('Hello again distributed logs');

constfiles=newwinston.transports.File({filename:'combined.log'});constconsole=newwinston.transports.Console();logger.clear()// Remove all transports.add(console)// Add console transport.add(files)// Add file transport.remove(console);// Remove console transport

constlogger=winston.createLogger({level:'info',transports:[newwinston.transports.Console(),newwinston.transports.File({filename:'combined.log'})]});//// Replaces the previous transports with those in the// new configuration wholesale.//constDailyRotateFile=require('winston-daily-rotate-file');logger.configure({level:'verbose',transports:[newDailyRotateFile(opts)]});

Creating child loggers

constlogger=winston.createLogger({transports:[newwinston.transports.Console(),]});constchildLogger=logger.child({requestId:'451'});

Streams,objectMode, andinfo objects

constinfo={level:'info',// Level of the logging messagemessage:'Hey! Log something?'// Descriptive message being logged.};

const{ level, message, ...meta}=info;

const{LEVEL,MESSAGE,SPLAT}=require('triple-beam');console.log(LEVEL===Symbol.for('level'));// trueconsole.log(MESSAGE===Symbol.for('message'));// trueconsole.log(SPLAT===Symbol.for('splat'));// true

Formats

const{ createLogger, format, transports}=require('winston');const{ combine, timestamp, label, printf}=format;constmyFormat=printf(({ level, message, label, timestamp})=>{return`${timestamp} [${label}]${level}:${message}`;});constlogger=createLogger({format:combine(label({label:'right meow!'}),timestamp(),myFormat),transports:[newtransports.Console()]});

Combining formats

const{ createLogger, format, transports}=require('winston');const{ combine, timestamp, label, prettyPrint}=format;constlogger=createLogger({format:combine(label({label:'right meow!'}),timestamp(),prettyPrint()),transports:[newtransports.Console()]})logger.log({level:'info',message:'What time is the testing at?'});// Outputs:// { level: 'info',//   message: 'What time is the testing at?',//   label: 'right meow!',//   timestamp: '2017-09-30T03:57:26.875Z'}

String interpolation

const{ createLogger, format, transports}=require('winston');constlogger=createLogger({format:format.combine(format.splat(),format.simple()),transports:[newtransports.Console()]});// info: test message my string {}logger.log('info','test message %s','my string');// info: test message 123 {}logger.log('info','test message %d',123);// info: test message first second {number: 123}logger.log('info','test message %s, %s','first','second',{number:123});

Filteringinfo Objects

const{ createLogger, format, transports}=require('winston');// Ignore log messages if they have { private: true }constignorePrivate=format((info,opts)=>{if(info.private){returnfalse;}returninfo;});constlogger=createLogger({format:format.combine(ignorePrivate(),format.json()),transports:[newtransports.Console()]});// Outputs: {"level":"error","message":"Public error to share"}logger.log({level:'error',message:'Public error to share'});// Messages with { private: true } will not be written when logged.logger.log({private:true,level:'error',message:'This is super secret - hide it.'});

const{ format}=require('winston');const{ combine, timestamp, label}=format;constwillNeverThrow=format.combine(format(info=>{returnfalse})(),// Ignores everythingformat(info=>{thrownewError('Never reached')})());

Creating custom formats

const{ format}=require('winston');constvolume=format((info,opts)=>{if(opts.yell){info.message=info.message.toUpperCase();}elseif(opts.whisper){info.message=info.message.toLowerCase();}returninfo;});// `volume` is now a function that returns instances of the format.constscream=volume({yell:true});console.dir(scream.transform({level:'info',message:`sorry for making you YELL in your head!`},scream.options));// {//   level: 'info'//   message: 'SORRY FOR MAKING YOU YELL IN YOUR HEAD!'// }// `volume` can be used multiple times to create different formats.constwhisper=volume({whisper:true});console.dir(whisper.transform({level:'info',message:`WHY ARE THEY MAKING US YELL SO MUCH!`},whisper.options));// {//   level: 'info'//   message: 'why are they making us yell so much!'// }

Logging Levels

{emerg:0,alert:1,crit:2,error:3,warning:4,notice:5,info:6,debug:7}

{error:0,warn:1,info:2,http:3,verbose:4,debug:5,silly:6}

Using Logging Levels

//// Any logger instance//logger.log('silly',"127.0.0.1 - there's no place like home");logger.log('debug',"127.0.0.1 - there's no place like home");logger.log('verbose',"127.0.0.1 - there's no place like home");logger.log('info',"127.0.0.1 - there's no place like home");logger.log('warn',"127.0.0.1 - there's no place like home");logger.log('error',"127.0.0.1 - there's no place like home");logger.info("127.0.0.1 - there's no place like home");logger.warn("127.0.0.1 - there's no place like home");logger.error("127.0.0.1 - there's no place like home");//// Default logger//winston.log('info',"127.0.0.1 - there's no place like home");winston.info("127.0.0.1 - there's no place like home");

constlogger=winston.createLogger({levels:winston.config.syslog.levels,transports:[newwinston.transports.Console({level:'error'}),newwinston.transports.File({filename:'combined.log',level:'info'})]});

consttransports={console:newwinston.transports.Console({level:'warn'}),file:newwinston.transports.File({filename:'combined.log',level:'error'})};constlogger=winston.createLogger({transports:[transports.console,transports.file]});logger.info('Will not be logged in either transport!');transports.console.level='info';transports.file.level='info';logger.info('Will be logged in both transports!');

Using Custom Logging Levels

constmyCustomLevels={levels:{foo:0,bar:1,baz:2,foobar:3},colors:{foo:'blue',bar:'green',baz:'yellow',foobar:'red'}};constcustomLevelLogger=winston.createLogger({levels:myCustomLevels.levels});customLevelLogger.foobar('some foobar level-ed message');

winston.addColors(myCustomLevels.colors);

baz:'italic yellow',foobar:'bold red cyanBG'

Colorizing Standard logging levels

winston.format.combine(winston.format.colorize(),winston.format.simple());

Colorizing full log line when json formatting logs

winston.format.combine(winston.format.json(),winston.format.colorize({all:true}));

Transports

Multiple transports of the same type

constlogger=winston.createLogger({transports:[newwinston.transports.File({filename:'combined.log',level:'info'}),newwinston.transports.File({filename:'errors.log',level:'error'})]});

constcombinedLogs=logger.transports.find(transport=>{returntransport.filename==='combined.log'});logger.remove(combinedLogs);

Adding Custom Transports

constTransport=require('winston-transport');constutil=require('util');//// Inherit from `winston-transport` so you can take advantage// of the base functionality and `.exceptions.handle()`.//module.exports=classYourCustomTransportextendsTransport{constructor(opts){super(opts);//// Consume any custom options here. e.g.:// - Connection information for databases// - Authentication information for APIs (e.g. loggly, papertrail,//   logentries, etc.).//}log(info,callback){setImmediate(()=>{this.emit('logged',info);});// Perform the writing to the remote servicecallback();}};

Common Transport options

constlogger=winston.createLogger({transports:[newwinston.transports.File({filename:'error.log',level:'error',format:winston.format.json()}),newwinston.transports.Http({level:'warn',format:winston.format.json()}),newwinston.transports.Console({level:'info',format:winston.format.combine(winston.format.colorize(),winston.format.simple())})]});

Exceptions

Handling Uncaught Exceptions with winston

const{ createLogger, transports}=require('winston');// Enable exception handling when you create your logger.constlogger=createLogger({transports:[newtransports.File({filename:'combined.log'})],exceptionHandlers:[newtransports.File({filename:'exceptions.log'})]});// Or enable it later on by adding a transport or using `.exceptions.handle`constlogger=createLogger({transports:[newtransports.File({filename:'combined.log'})]});// Call exceptions.handle with a transport to handle exceptionslogger.exceptions.handle(newtransports.File({filename:'exceptions.log'}));

//// You can add a separate exception logger by passing it to `.exceptions.handle`//winston.exceptions.handle(newwinston.transports.File({filename:'path/to/exceptions.log'}));//// Alternatively you can set `handleExceptions` to true when adding transports// to winston.//winston.add(newwinston.transports.File({filename:'path/to/combined.log',handleExceptions:true}));

To Exit or Not to Exit

constlogger=winston.createLogger({exitOnError:false});//// or, like this://logger.exitOnError=false;

Example 1

constlogger=winston.createLogger({transports:[newwinston.transports.File({filename:'path/to/combined.log'})],exceptionHandlers:[newwinston.transports.File({filename:'path/to/exceptions.log'})]});

Example 2

constlogger=winston.createLogger({transports:[newwinston.transports.Console({handleExceptions:true})],exitOnError:false});

functionignoreEpipe(err){returnerr.code!=='EPIPE';}constlogger=winston.createLogger({exitOnError:ignoreEpipe});//// or, like this://logger.exitOnError=ignoreEpipe;

Rejections

Handling Uncaught Promise Rejections with winston

const{ createLogger, transports}=require('winston');// Enable rejection handling when you create your logger.constlogger=createLogger({transports:[newtransports.File({filename:'combined.log'})],rejectionHandlers:[newtransports.File({filename:'rejections.log'})]});// Or enable it later on by adding a transport or using `.rejections.handle`constlogger=createLogger({transports:[newtransports.File({filename:'combined.log'})]});// Call rejections.handle with a transport to handle rejectionslogger.rejections.handle(newtransports.File({filename:'rejections.log'}));

//// You can add a separate rejection logger by passing it to `.rejections.handle`//winston.rejections.handle(newwinston.transports.File({filename:'path/to/rejections.log'}));//// Alternatively you can set `handleRejections` to true when adding transports// to winston.//winston.add(newwinston.transports.File({filename:'path/to/combined.log',handleRejections:true}));

Profiling

//// Start profile of 'test'//logger.profile('test');setTimeout(function(){//// Stop profile of 'test'. Logging will now take place://   '17 Jan 21:00:00 - info: test duration=1000ms'//logger.profile('test');},1000);

// Returns an object corresponding to a specific timing. When done// is called the timer will finish and log the duration. e.g.://constprofiler=logger.startTimer();setTimeout(function(){profiler.done({message:'Logging message'});},1000);

logger.profile('test',{level:'debug'});

Querying Logs

constoptions={from:newDate()-(24*60*60*1000),until:newDate(),limit:10,start:0,order:'desc',fields:['message']};//// Find items logged between today and yesterday.//logger.query(options,function(err,results){if(err){/* TODO: handle me */throwerr;}console.log(results);});

Streaming Logs

//// Start at the end.//winston.stream({start:-1}).on('log',function(log){console.log(log);});

Further Reading

Using the Default Logger

constwinston=require('winston');winston.log('info','Hello distributed log files!');winston.info('Hello again distributed logs');winston.level='debug';winston.log('debug','Now my debug messages are written to console!');

constfiles=newwinston.transports.File({filename:'combined.log'});constconsole=newwinston.transports.Console();winston.add(console);winston.add(files);winston.remove(console);

winston.configure({transports:[newwinston.transports.File({filename:'somefile.log'})]});

Awaiting logs to be written inwinston

consttransport=newwinston.transports.Console();constlogger=winston.createLogger({transports:[transport]});logger.on('finish',function(info){// All `info` log messages has now been logged});logger.info('CHILL WINSTON!',{seriously:true});logger.end();

//// Handle errors originating in the logger itself//logger.on('error',function(err){/* Do Something */});

Working with multiple Loggers in winston

constwinston=require('winston');const{ format}=winston;const{ combine, label, json}=format;//// Configure the logger for `category1`//winston.loggers.add('category1',{format:combine(label({label:'category one'}),json()),transports:[newwinston.transports.Console({level:'silly'}),newwinston.transports.File({filename:'somefile.log'})]});//// Configure the logger for `category2`//winston.loggers.add('category2',{format:combine(label({label:'category two'}),json()),transports:[newwinston.transports.Http({host:'localhost',port:8080})]});

constwinston=require('winston');//// Grab your preconfigured loggers//constcategory1=winston.loggers.get('category1');constcategory2=winston.loggers.get('category2');category1.info('logging to file and console transports');category2.info('logging to http transport');

constwinston=require('winston');const{ format}=winston;const{ combine, label, json}=format;constcontainer=newwinston.Container();container.add('category1',{format:combine(label({label:'category one'}),json()),transports:[newwinston.transports.Console({level:'silly'}),newwinston.transports.File({filename:'somefile.log'})]});constcategory1=container.get('category1');category1.info('logging to file and console transports');

Routing Console transport messages to the console instead of stdout and stderr

constlogger=winston.createLogger({level:'info',transports:[newwinston.transports.Console({forceConsole:true})]});

Installation

npm install winston

yarn add winston

Run Tests

npmtest# Runs all testsnpm run test:unit# Runs all Unit tests with coveragenpm run test:integration# Runs all integration testsnpm run test:typescript# Runs tests verifying Typescript types

Author:Charlie Robbins

Contributors:Jarrett Cruger,David Hyde,Chris Alderson,Jonathon Terry