winston

What is winston?

Winston is a versatile logging library for Node.js. It is designed to be a simple and universal logging library with support for multiple transports. A transport is essentially a storage device for your logs. Winston allows you to query your logs and can be extended with custom transports, which means that you can write your own storage devices. It is also capable of logging with different levels of severity, which can be useful for filtering logs based on importance.

What are winston's main functionalities?

Logging with different severity levels

This code sets up Winston to log messages of different severity levels, which include error, warn, info, verbose, debug, and silly. It also demonstrates how to add multiple transports; in this case, it logs to two files and optionally to the console when not in production.

{"const winston = require('winston');\nconst logger = winston.createLogger({\n  level: 'info',\n  format: winston.format.json(),\n  transports: [\n    new winston.transports.File({ filename: 'error.log', level: 'error' }),\n    new winston.transports.File({ filename: 'combined.log' })\n  ]\n});\n\nif (process.env.NODE_ENV !== 'production') {\n  logger.add(new winston.transports.Console({\n    format: winston.format.simple()\n  }));\n}\n\nlogger.error('Error log example');\nlogger.warn('Warning log example');\nlogger.info('Information log example');\nlogger.verbose('Verbose log example');\nlogger.debug('Debug log example');\nlogger.silly('Silly log example');"}

Custom log formats

This code demonstrates how to create a custom log format using Winston's format.combine method. It includes a timestamp and prints the log level and message in a custom format.

{"const winston = require('winston');\nconst logger = winston.createLogger({\n  transports: [\n    new winston.transports.Console()\n  ],\n  format: winston.format.combine(\n    winston.format.timestamp({\n      format: 'YYYY-MM-DD HH:mm:ss'\n    }),\n    winston.format.printf(info => `${info.timestamp} ${info.level}: ${info.message}`)\n  )\n});\n\nlogger.info('Custom format log example');"}

Querying logs

This code snippet shows how to query logs from a file transport. It retrieves logs from the last 24 hours, limits the results to 10, and orders them in descending order.

{"const winston = require('winston');\nconst logger = winston.createLogger({\n  transports: [\n    new winston.transports.File({ filename: 'combined.log' })\n  ]\n});\n\nlogger.query({\n  from: new Date() - (24 * 60 * 60 * 1000),\n  until: new Date(),\n  limit: 10,\n  start: 0,\n  order: 'desc',\n}, function (err, results) {\n  if (err) {\n    throw err;\n  }\n  console.log(results);\n});"}

Other packages similar to winston

bunyan

Bunyan is a simple and fast JSON logging library for Node.js services. Like Winston, it supports multiple streams and custom levels. Bunyan's main difference is that it focuses on JSON logging, and it comes with a CLI tool for pretty-printing log files.

pino

Pino is a very low-overhead Node.js logger, which claims to be significantly faster than alternatives like Winston and Bunyan, especially in scenarios where performance is critical. Pino focuses on delivering the essential logging features with the smallest impact on performance.

log4js

Log4js is another logging library inspired by the Java library log4j. It supports multiple appenders, log levels, and has a similar configuration style to log4j. Log4js can be a good alternative if you're looking for a logging solution with a familiar configuration style to Java's log4j.

README

winston

A multi-transport async logging library for node.js. "CHILL WINSTON! ... I put it in the logs."

Installation

Installing npm (node package manager)

  curl http://npmjs.org/install.sh | sh

Installing winston

  [sudo] npm install winston

Motivation

Winston is designed to be a simple and universal logging library with support for multiple transports. A transport is essentially a storage device for your logs. Each instance of a winston logger can have multiple transports configured at different levels. For example, one may want error logs to be stored in a persistent remote location (like a database), but all logs output to the console or a local file.

There also seemed to be a lot of logging libraries out there that coupled their implementation of logging (i.e. how the logs are stored / indexed) to the API that they exposed to the programmer. This library aims to decouple those parts of the process to make it more flexible and extensible.

Usage

There are two different ways to use winston: directly via the default logger, or by instantiating your own Logger. The former is merely intended to be a convenient shared logger to use throughout your application if you so choose.

Using the Default Logger

The default logger is accessible through the winston module directly. Any method that you could call on an instance of a logger is available on the default logger:

  var winston = require('winston');
  
  winston.log('info', 'Hello distributed log files!');
  winston.info('Hello again distributed logs');

By default, only the Console transport is set on the default logger. You can add or remove transports via the add() and remove() methods:

  winston.add(winston.transports.File, { filename: 'somefile.log' });
  winston.remove(winston.transports.Console);

For more documenation about working with each individual transport supported by Winston see the "Working with Transports" section below.

Instantiating your own Logger

If you would prefer to manage the object lifetime of loggers you are free to instantiate them yourself:

  var logger = new (winston.Logger)({
    transports: [
      new (winston.transports.Console)(),
      new (winston.transports.File)({ filename: 'somefile.log' })
    ]
  });

You can work with this logger in the same way that you work with the default logger:

  //
  // Logging
  //
  logger.log('info', 'Hello distributed log files!');
  logger.info('Hello again distributed logs');
  
  //
  // Adding / Removing Transports
  //   (Yes It's chainable)
  //
  logger.add(winston.transports.File)
        .remove(winston.transports.Console);

Handling Uncaught Exceptions with winston

With winston, it is possible to catch and log uncaughtException events from your process. There are two distinct ways of enabling this functionality either through the default winston logger or your own logger instance.

If you want to use this feature with the default logger simply call .handleExceptions() with a transport instance.

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

to exit or not to exit

by default, winston will exit after logging an uncaughtException. if this is not the behavior you want, set exitOnError = false

var logger = new (winston.Logger)({exitOnError: false})

//or, like this:

logger.exitOnError = false

When working with custom logger instances, you can pass in separate transports to the exceptionHandlers property or set .handleExceptions on any transport.

  var logger = new (winston.Logger)({
    transports: [
      new winston.transports.File({ filename: 'path/to/all-logs.log' })
    ]
    exceptionHandlers: [
      new winston.transports.File({ filename: 'path/to/exceptions.log' })
    ]
  });

Using Logging Levels

Setting the level for your logging message can be accomplished in one of two ways. You can pass a string representing the logging level to the log() method or use the level specified methods defined on every winston Logger.

  //
  // Any logger instance
  //
  logger.log('info', "127.0.0.1 - there's no place like home");
  logger.info("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");

As of 0.2.0, winston supports customizable logging levels, defaulting to npm style logging levels. Changing logging levels is easy:

  //
  // Change levels on the default winston logger
  //
  winston.setLevels(winston.config.syslog.levels);
  
  //
  // Change levels on an instance of a logger
  //
  logger.setLevels(winston.config.syslog.levels);

Calling .setLevels on a logger will remove all of the previous helper methods for the old levels and define helper methods for the new levels. Thus, you should be careful about the logging statements you use when changing levels. For example, if you ran this code after changing to the syslog levels:

  //
  // Logger does not have 'silly' defined since that level is not in the syslog levels 
  //
  logger.silly('some silly message');

Using Custom Logging Levels

In addition to the predefined npm and syslog levels available in Winston, you can also choose to define your own:

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

Although there is slight repetition in this data structure, it enables simple encapsulation if you not to have colors. If you do wish to have colors, in addition to passing the levels to the Logger itself, you must make winston aware of them:

  //
  // Make winston aware of these colors
  //
  winston.addColors(myCustomLevels.colors);

This enables transports with the 'colorize' option set to appropriately color the output of custom levels.

Events and Callbacks in Winston

Each instance of winston.Logger is also an instance of an EventEmitter. A log event will be raised each time a transport successfully logs a message:

  logger.on('log', function (transport, level, msg, meta) {
    // [msg] and [meta] have now been logged at [level] to [transport]
  });
  
  logger.info('CHILL WINSTON!', { seriously: true });

It is also worth mentioning that the logger also emits an 'error' event which you should handle or suppress if you don't want unhandled exceptions:

  //
  // Handle errors
  //
  logger.on('error', function (err) { /* Do Something */ });
  
  //
  // Or just suppress them.
  //
  logger.emitErrs = false;

Every logging method described in the previous section also takes an optional callback which will be called only when all of the transports have logged the specified message.

  logger.info('CHILL WINSTON!', { seriously: true }, function (err, level, msg, meta) {
    // [msg] and [meta] have now been logged at [level] to **every** transport.
  });

Working with multiple Loggers in winston

Often in larger, more complex applications it is necessary to have multiple logger instances with different settings. Each logger is responsible for a different feature area (or category). This is exposed in winston in two ways: through winston.loggers and instances of winston.Container. In fact, winston.loggers is just a predefined instance of winston.Container:

  var winston = require('winston');
  
  //
  // Configure the logger for `category1`
  //
  winston.loggers.add('category1', {
    console: {
      level: 'silly',
      colorize: 'true'
    },
    file: {
      filename: '/path/to/some/file'
    }
  });
  
  //
  // Configure the logger for `category2`
  //
  winston.loggers.add('category2', {
    couchdb: {
      host: '127.0.0.1',
      port: 5984
    }
  });

Now that your loggers are setup you can require winston in any file in your application and access these pre-configured loggers:

  var winston = require('winston');
  
  //
  // Grab your preconfigured logger
  //
  var category1 = winston.loggers.get('category1');
  
  category1.info('logging from your IoC container-based logger');

If you prefer to manage the Container yourself you can simply instantiate one:

  var winston = require('winston'),
      container = new winston.Container();
  
  container.add('category1', {
    console: {
      level: 'silly',
      colorize: 'true'
    },
    file: {
      filename: '/path/to/some/file'
    }
  });

Sharing transports between Loggers in winston

  var winston = require('winston');

  //
  // Setup transports to be shared across all loggers
  // in three ways:
  //
  // 1. By setting it on the default Container
  // 2. By passing `transports` into the constructor function of winston.Container
  // 3. By passing `transports` into the `.get()` or `.add()` methods 
  //

  //
  // 1. By setting it on the default Container
  //
  winston.loggers.options.transports = [
    // Setup your shared transports here
  ];

  //
  // 2. By passing `transports` into the constructor function of winston.Container
  //
  var container = new winston.Container({
    transports: [
      // Setup your shared transports here
    ]
  });

  //
  // 3. By passing `transports` into the `.get()` or `.add()` methods 
  // 
  winston.loggers.add('some-category', {
    transports: [
      // Setup your shared transports here
    ]
  });

  container.add('some-category', {
    transports: [
      // Setup your shared transports here
    ]
  });

Logging with Metadata

In addition to logging string messages, winston will also optionally log additional JSON metadata objects. Adding metadata is simple:

  winston.log('info', 'Test Log Message', { anything: 'This is metadata' });

The way these objects is stored varies from transport to transport (to best support the storage mechanisms offered). Here's a quick summary of how each transports handles metadata:

1. Console: Logged via util.inspect(meta)
2. File: Logged via util.inspect(meta)
3. Loggly: Logged in suggested Loggly format

Profiling with Winston

In addition to logging messages and metadata, winston also has a simple profiling mechanism implemented for any logger:

  //
  // Start profile of 'test'
  // Remark: Consider using Date.now() with async operations 
  //
  winston.profile('test');
  
  setTimeout(function () {
    //
    // Stop profile of 'test'. Logging will now take place:
    //   "17 Jan 21:00:00 - info: test duration=1000ms"
    //
    winston.profile('test');
  }, 1000);

All profile messages are set to the 'info' by default and both message and metadata are optional There are no plans in the Roadmap to make this configurable, but I'm open to suggestions / issues.

Using winston in a CLI tool

A common use-case for logging is output to a CLI tool. Winston has a special helper method which will pretty print output from your CLI tool. Here's an example from the require-analyzer written by Nodejitsu:

  info:   require-analyzer starting in /Users/Charlie/Nodejitsu/require-analyzer
  info:   Found existing dependencies
  data:   {
  data:     colors: '0.x.x',
  data:     eyes: '0.1.x',
  data:     findit: '0.0.x',
  data:     npm: '1.0.x',
  data:     optimist: '0.2.x',
  data:     semver: '1.0.x',
  data:     winston: '0.2.x'
  data:   }
  info:   Analyzing dependencies...
  info:   Done analyzing raw dependencies
  info:   Retrieved packages from npm
  warn:   No additional dependencies found

Configuring output for this style is easy, just use the .cli() method on winston or an instance of winston.Logger:

  var winston = require('winston');
  
  //
  // Configure CLI output on the default logger
  //
  winston.cli();
  
  //
  // Configure CLI on an instance of winston.Logger
  //
  var logger = new winston.Logger({
    transports: [
      new (winston.transports.Console)()
    ]
  });
  
  logger.cli();

Extending another object with Logging functionality

Often in a given code base with lots of Loggers it is useful to add logging methods a different object so that these methods can be called with less syntax. Winston exposes this functionality via the 'extend' method:

  var myObject = {};
  
  logger.extend(myObject);
  
  //
  // You can now call logger methods on 'myObject'
  //
  myObject.info('127.0.0.1 - there's no place like home');

Working with Transports

Right now there are four transports supported by winston core. If you have a transport you would like to add either open an issue or fork and submit a pull request. Commits are welcome, but I'll give you extra street cred if you add tests too :D

1. Console: Output to the terminal
2. Files: Append to a file
3. Loggly: Log to Logging-as-a-Service platform Loggly

Console Transport

  winston.add(winston.transports.Console, options)

The Console transport takes two simple options:

• level: Level of messages that this transport should log.
• silent: Boolean flag indicating whether to suppress output
• colorize: Boolean flag indicating if we should colorize output.

Metadata: Logged via util.inspect(meta);

File Transport

  winston.add(winston.transports.File, options)

The File transport should really be the 'Stream' transport since it will accept any WritableStream. It is named such because it will also accept filenames via the 'filename' option:

• level: Level of messages that this transport should log.
• silent: Boolean flag indicating whether to suppress output.
• colorize: Boolean flag indicating if we should colorize output.
• filename: The filename of the logfile to write output to.
• stream: The WriteableStream to write output to.

Metadata: Logged via util.inspect(meta);

Loggly Transport

  winston.add(winston.transports.Loggly, options);

The Loggly transport is based on Nodejitsu's node-loggly implementation of the Loggly API. If you haven't heard of Loggly before, you should probably read their value proposition. The Loggly transport takes the following options. Either 'inputToken' or 'inputName' is required:

• level: Level of messages that this transport should log.
• subdomain: The subdomain of your Loggly account. [required]
• auth: The authentication information for your Loggly account. [required with inputName]
• inputName: The name of the input this instance should log to.
• inputToken: The input token of the input this instance should log to.
• json: If true, messages will be sent to Loggly as JSON.

Metadata: Logged in suggested Loggly format

Riak Transport

As of 0.3.0 the Riak transport has been broken out into a new module: winston-riak. Using it is just as easy:

  var Riak = require('winston-riak').Riak;
  winston.add(Riak, options);

In addition to the options accepted by the riak-js client, the Riak transport also accepts the following options. It is worth noting that the riak-js debug option is set to false by default:

• level: Level of messages that this transport should log.
• bucket: The name of the Riak bucket you wish your logs to be in or a function to generate bucket names dynamically.

  // Use a single bucket for all your logs
  var singleBucketTransport = new (Riak)({ bucket: 'some-logs-go-here' });
  
  // Generate a dynamic bucket based on the date and level
  var dynamicBucketTransport = new (Riak)({
    bucket: function (level, msg, meta, now) {
      var d = new Date(now);
      return level + [d.getDate(), d.getMonth(), d.getFullYear()].join('-');
    }
  });

Metadata: Logged as JSON literal in Riak

MongoDB Transport

As of 0.3.0 the MongoDB transport has been broken out into a new module: winston-mongodb. Using it is just as easy:

  var MongoDB = require('winston-mongodb').MongoDB;
  winston.add(MongoDB, options);

The MongoDB transport takes the following options. 'db' is required:

• level: Level of messages that this transport should log.
• silent: Boolean flag indicating whether to suppress output.
• db: The name of the database you want to log to. [required]
• collection: The name of the collection you want to store log messages in, defaults to 'log'.
• safe: Boolean indicating if you want eventual consistency on your log messages, if set to true it requires an extra round trip to the server to ensure the write was committed, defaults to true.
• host: The host running MongoDB, defaults to localhost.
• port: The port on the host that MongoDB is running on, defaults to MongoDB's default port.

Metadata: Logged as a native JSON object.

Adding Custom Transports

Adding a custom transport (say for one of the datastore on the Roadmap) is actually pretty easy. All you need to do is accept a couple of options, set a name, implement a log() method, and add it to the set of transports exposed by winston.

  var util = require('util'),
      winston = require('winston');
  
  var CustomLogger = winston.transports.CustomerLogger = function (options) {
    //
    // Name this logger
    //
    this.name = 'customLogger';
    
    //
    // Set the level from your options
    //
    this.level = options.level || 'info';
    
    //
    // Configure your storage backing as you see fit
    //
  };
  
  //
  // Inherit from `winston.Transport` so you can take advantage
  // of the base functionality and `.handleExceptions()`.
  //
  util.inherits(CustomLogger, winston.Transport);
  
  CustomLogger.prototype.log = function (level, msg, meta, callback) {
    //
    // Store this message and metadata, maybe use some custom logic
    // then callback indicating success.
    //
    callback(null, true); 
  };

What's Next?

Winston is stable and under active development. It is supported by and used at Nodejitsu.

Inspirations

1. npm
2. log.js
3. socket.io
4. node-rlog
5. BigBrother
6. Loggly

Road Map

1. Graylog2 format support.
2. Improve support for adding custom Transports not defined in Winston core.
3. Create API for reading from logs across all transports.
4. Add more transports: Redis

Run Tests

All of the winston tests are written in vows, and cover all of the use cases described above. You will need to add valid credentials for the various transports included to test/test-config.json before running tests:

  {
    "transports": {
      "loggly": {
        "subdomain": "your-subdomain",
        "inputToken": "really-long-token-you-got-from-loggly",
        "auth": {
          "username": "your-username",
          "password": "your-password"
        }
      }
    }
  }

Once you have valid configuration and credentials you can run tests with vows:

  vows --spec --isolate

Author: Charlie Robbins

Contributors: Matthew Bergman, Marak Squires