Merge pull request #732 from winstonjs/2.x

winston@2.0.0

.travis.yml

@@ -14,6 +14,8 @@ script:
 
 matrix:
   allow_failures:
+    - node_js: "0.8"
+    - node_js: "0.10"
     - node_js: "0.12"
 
 notifications:

CHANGELOG.md

@@ -1,3 +1,35 @@
+## v2.0.0 / 2015-10-29
+### OMG IT'S MY SISTER'S BIRTHDAY EDITION
+
+#### Breaking changes
+
+**Most important**
+- **[0f82204](https://github.com/winstonjs/winston/commit/0f82204) Move `winston.transports.DailyRotateFile` [into a separate module](https://github.com/winstonjs/winston-daily-rotate-file)**: `require('winston-daily-rotate-file');`
+- **[fb9eec0](https://github.com/winstonjs/winston/commit/fb9eec0) Reverse log levels in `npm` and `cli` configs to conform to [RFC524](https://tools.ietf.org/html/rfc5424). Fixes [#424](https://github.com/winstonjs/winston/pull/424) [#406](https://github.com/winstonjs/winston/pull/406) [#290](https://github.com/winstonjs/winston/pull/290)**
+- **[8cd8368](https://github.com/winstonjs/winston/commit/8cd8368) Change the method signature to a `filter` function to be consistent with `rewriter` and log functions:**
+``` js
+function filter (level, msg, meta, inst) {
+  // Filter logic goes here...
+}
+```
+
+**Other breaking changes**
+- [e0c9dde](https://github.com/winstonjs/winston/commit/e0c9dde) Remove `winston.transports.Webhook`. Use `winston.transports.Http` instead.
+- [f71e638](https://github.com/winstonjs/winston/commit/f71e638) Remove `Logger.prototype.addRewriter` and `Logger.prototype.addFilter` since they just push to an Array of functions. Use `logger.filters.push` or `logger.rewriters.push` explicitly instead.
+- [a470ab5](https://github.com/winstonjs/winston/commit/a470ab5) No longer respect the `handleExceptions` option to `new winston.Logger`. Instead just pass in the `exceptionHandlers` option itself.
+- [8cb7048](https://github.com/winstonjs/winston/commit/8cb7048) Removed `Logger.prototype.extend` functionality
+
+#### New features
+- [3aa990c](https://github.com/winstonjs/winston/commit/3aa990c) Added `Logger.prototype.configure` which now contains all logic previously in the `winston.Logger` constructor function. (`indexzero`)
+- [#726](https://github.com/winstonjs/winston/pull/726) Update .npmignore (`coreybutler`)
+- [#700](https://github.com/winstonjs/winston/pull/700) Add an `eol` option to the `Console` transport. (`aquavitae`)
+- [#731](https://github.com/winstonjs/winston/pull/731) Update `lib/transports.js` for better static analysis. (`indexzero`)
+
+#### Fixes, refactoring, and optimizations. OH MY!
+- [#632](https://github.com/winstonjs/winston/pull/632) Allow `File` transport to be an `objectMode` writable stream. (`stambata`)
+- [#527](https://github.com/winstonjs/winston/issues/527), [163f4f9](https://github.com/winstonjs/winston/commit/163f4f9), [3747ccf](https://github.com/winstonjs/winston/commit/3747ccf) Performance optimizations and string interpolation edge cases (`indexzero`)
+- [f0edafd](https://github.com/winstonjs/winston/commit/f0edafd) Code cleanup for reability, ad-hoc styleguide enforcement (`indexzero`)
+
 ## v1.1.1 - v1.1.2 / 2015-10
 ### MINOR FIXES EDITION
 

README.md

@@ -38,7 +38,6 @@ There are two different ways to use winston: directly via the default logger, or
   * [Events and Callbacks in Winston](#events-and-callbacks-in-winston)
   * [Working with multiple Loggers in winston](#working-with-multiple-loggers-in-winston)
   * [Using winston in a CLI tool](#using-winston-in-a-cli-tool)
-  * [Extending another object with Logging](#extending-another-object-with-logging)
   * [Filters and Rewriters](#filters-and-rewriters)
   * [Adding Custom Transports](#adding-custom-transports)
 * [Installation](#installation)
@@ -47,6 +46,8 @@ There are two different ways to use winston: directly via the default logger, or
 
 ## Logging
 
+Logging levels in `winston` conform to the severity ordering specified by [RFC524](https://tools.ietf.org/html/rfc5424): _severity of all levels is assumed to be numerically **ascending** from most important to least important._
+
 ### 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:
 
@@ -94,10 +95,35 @@ You can work with this logger in the same way that you work with the default log
   // Adding / Removing Transports
   //   (Yes It's chainable)
   //
-  logger.add(winston.transports.File)
-        .remove(winston.transports.Console);
+  logger
+    .add(winston.transports.File)
+    .remove(winston.transports.Console);
 ```
 
+You can also wholesale reconfigure a `winston.Logger` instance using the `configure` method:
+
+``` js
+  var logger = new winston.Logger({
+    level: 'info',
+    transports: [
+      new (winston.transports.Console)(),
+      new (winston.transports.File)({ filename: 'somefile.log' })
+    ]
+  });
+
+  //
+  // Replaces the previous transports with those in the
+  // new configuration wholesale.
+  //
+  logger.configure({
+    level: 'verbose',
+    transports: [
+      new require('winston-daily-rotate-file')(opts)
+    ]
+  });
+```
+
+
 ### Logging with Metadata
 In addition to logging string messages, winston will also optionally log additional JSON metadata objects. Adding metadata is simple:
 
@@ -327,6 +353,20 @@ The `exitOnError` option can also be a function to prevent exit on only certain
 
 ## Logging Levels
 
+Each `level` is given a specific integer priority. The higher the priority the more important the message is considered to be, and the lower the corresponding integer priority.  For example, `npm` logging levels are prioritized from 0 to 5 (highest to lowest):
+
+``` js
+{ error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5 }
+```
+
+Similarly, as specified exactly in RFC524 the `syslog` levels are prioritized from 0 to 7 (highest to lowest).
+
+```js
+{ emerg: 0, alert: 1, crit: 2, error: 3, warning: 4, notice: 5, info: 6, debug: 7 }
+```
+
+If you do not explicitly define the levels that `winston` should use the `npm` levels above will be used.
+
 ### 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.
 
@@ -351,13 +391,16 @@ Setting the level for your logging message can be accomplished in one of two way
   winston.info("127.0.0.1 - there's no place like home");
 ```
 
-Winston allows you to set a `level` on each transport that specifies the level of messages this transport should log. For example, you could log only errors to the console, with the full logs in a file (note that the default level of a transport is `info`):
+`winston` allows you to define a `level` property on each transport which specifies the **maximum** level of messages that a transport should log. For example, using the `npm` levels you could log only `error` messages to the console and everything `info` and below to a file (which includes `error` messages):
 
 ``` js
   var logger = new (winston.Logger)({
     transports: [
       new (winston.transports.Console)({ level: 'error' }),
-      new (winston.transports.File)({ filename: 'somefile.log' })
+      new (winston.transports.File)({
+        filename: 'somefile.log',
+        level: 'info'
+      })
     ]
   });
 ```
@@ -620,25 +663,22 @@ Configuring output for this style is easy, just use the `.cli()` method on `wins
   logger.cli();
 ```
 
-### Extending another object with Logging
-Often in a given code base with lots of Loggers it is useful to add logging methods to a different object so that these methods can be called with less syntax. Winston exposes this functionality via the 'extend' method:
-
-``` js
-  var myObject = {};
+### Filters and Rewriters
+Filters allow modifying the contents of **log messages**, and Rewriters allow modifying the contents of **log meta** e.g. to mask data that should not appear in logs.
 
-  logger.extend(myObject);
+Both filters and rewriters are simple Arrays of functions which can be provided when creating a `new winston.Logger(options)`. e.g.:
 
-  //
-  // You can now call logger methods on 'myObject'
-  //
-  myObject.info("127.0.0.1 - there's no place like home");
+``` js
+var logger = new winston.Logger({
+  rewriters: [function (level, msg, meta) { /* etc etc */ }]
+  filters:   [function (level, msg, meta) { /* etc etc */ }]
+})
 ```
 
-### Filters and Rewriters
-Filters allow modifying the contents of **log messages**, and Rewriters allow modifying the contents of **log meta** e.g. to mask data that should not appear in logs.
+Like any Array they can also be modified at runtime with no adverse side-effects to the `winston` internals.
 
 ``` js
-logger.addFilter(function(msg, meta, level) {
+logger.filters.push(function(level, msg, meta) {
   return meta.production
     ? maskCardNumbers(msg)
     : msg;
@@ -656,7 +696,7 @@ info: transaction with card number 123456****2345 successful.
 Where as for rewriters, if you wanted to sanitize the `creditCard` field of your `meta` you could:
 
 ``` js
-logger.addRewriter(function(level, msg, meta) {
+logger.rewriters.push(function(level, msg, meta) {
   if (meta.creditCard) {
     meta.creditCard = maskCardNumbers(meta.creditCard)
   }

docs/transports.md

@@ -7,7 +7,6 @@ There are several [core transports](#winston-core) included in `winston`, which
 * **[Winston Core](#winston-core)**
   * [Console](#console-transport)
   * [File](#file-transport)
-  * [DailyRotateFile](#dailyrotatefile-transport)
   * [Http](#http-transport)
 
 * **[Winston More](#winston-more)**
@@ -35,7 +34,6 @@ There are several core transports included in `winston`, which leverage the buil
 
 * [Console](#console-transport)
 * [File](#file-transport)
-* [DailyRotateFile](#dailyrotatefile-transport)
 * [Http](#http-transport)
 
 ### Console Transport
@@ -90,32 +88,6 @@ The File transport should really be the 'Stream' transport since it will accept
 
 *Metadata:* Logged via util.inspect(meta);
 
-
-### DailyRotateFile Transport
-
-``` js
-  winston.add(winston.transports.DailyRotateFile, options)
-```
-
-The DailyRotateFile transport can rotate files by minute, hour, day, month or year. Its options are identical to the File transport with the lone addition of the 'datePattern' option:
-
-* __datePattern:__ A string representing the pattern to be used when appending the date to the filename (default '.yyyy-MM-dd'). The meta characters used in this string will dictate the frequency of the file rotation. For example if your datePattern is simply '.HH' you will end up with 24 log files that are picked up and appended to every day.
-
-Valid meta characters in the datePattern are:
-
-* __yy:__ Last two digits of the year.
-* __yyyy:__ Full year.
-* __M:__ The month.
-* __MM:__ The zero padded month.
-* __d:__ The day.
-* __dd:__ The zero padded day.
-* __H:__ The hour.
-* __HH:__ The zero padded hour.
-* __m:__ The minute.
-* __mm:__ The zero padded minute.
-
-*Metadata:* Logged via util.inspect(meta);
-
 ### Http Transport
 
 ``` js

examples/couchdb.js

@@ -5,7 +5,7 @@ var winston = require('../lib/winston');
 //
 //
 // The Console transport will simply output to the console screen
-// The Couchdb tranport will perform an HTTP POST request to the specified CouchDB instance
+// The CouchDB tranport will perform an HTTP POST request to the specified CouchDB instance
 //
 var logger = new (winston.Logger)({
   transports: [
@@ -15,4 +15,4 @@ var logger = new (winston.Logger)({
   ]
 });
 
-logger.log('info', 'Hello webhook log files!', { 'foo': 'bar' });
+logger.log('info', 'Hello log files!', { 'foo': 'bar' });

examples/custom-levels.js

@@ -12,22 +12,22 @@ var winston = require('../lib/winston');
 //
 var config = {
   levels: {
-    silly: 0,
-    verbose: 1,
-    info: 2,
+    error: 0,
+    debug: 1,
+    warn: 2,
     data: 3,
-    warn: 4,
-    debug: 5,
-    error: 6
+    info: 4,
+    verbose: 5,
+    silly: 6
   },
   colors: {
-    silly: 'magenta',
-    verbose: 'cyan',
-    info: 'green',
-    data: 'grey',
-    warn: 'yellow',
+    error: 'red',
     debug: 'blue',
-    error: 'red'
+    warn: 'yellow',
+    data: 'grey',
+    info: 'green',
+    verbose: 'cyan',
+    silly: 'magenta'
   }
 };
 
@@ -41,4 +41,4 @@ var logger = module.exports = new (winston.Logger)({
   colors: config.colors
 });
 
-logger.data('hello')
+logger.data('hello')

examples/interpolation.js

@@ -0,0 +1,12 @@
+var w = require('./');
+
+w.info('Found %s at %s', 'error', new Date());
+w.info('Found %s at %s', 'error', new Error('chill winston'));
+w.info('Found %s at %s', 'error', /WUT/);
+w.info('Found %s at %s', 'error', true);
+w.info('Found %s at %s', 'error', 100.00);
+w.info('Found %s at %s', 'error', ['1, 2, 3']);
+// prints "Found error at %s"
+
+// console.log('Found %s at %s', 'error', new Date())
+// prints "Found error at Tue Jan 20 2015 10:14:26 GMT-0800 (PST)"

lib/winston/config.js

@@ -23,15 +23,18 @@ config.colorize = function (level, message) {
     for (var i = 0, l = allColors[level].length; i < l; ++i) {
       colorized = colors[allColors[level][i]](colorized);
     }
-  } else if (allColors[level].match(/\s/)) {
+  }
+  else if (allColors[level].match(/\s/)) {
     var colorArr = allColors[level].split(/\s+/);
     for (var i = 0; i < colorArr.length; ++i) {
       colorized = colors[colorArr[i]](colorized);
     }
     allColors[level] = colorArr;
-  } else {
+  }
+  else {
     colorized = colors[allColors[level]](colorized);
   }
+
   return colorized;
 };
 

lib/winston/config/cli-config.js

@@ -9,27 +9,27 @@
 var cliConfig = exports;
 
 cliConfig.levels = {
-  silly: 0,
-  input: 1,
-  verbose: 2,
-  prompt: 3,
-  debug: 4,
-  info: 5,
-  data: 6,
-  help: 7,
-  warn: 8,
-  error: 9
+  error: 0,
+  warn: 1,
+  help: 2,
+  data: 3,
+  info: 4,
+  debug: 5,
+  prompt: 6,
+  verbose: 7,
+  input: 8,
+  silly: 9,
 };
 
 cliConfig.colors = {
-  silly: 'magenta',
-  input: 'grey',
-  verbose: 'cyan',
-  prompt: 'grey',
-  debug: 'blue',
-  info: 'green',
-  data: 'grey',
-  help: 'cyan',
+  error: 'red',
   warn: 'yellow',
-  error: 'red'
-};
+  help: 'cyan',
+  data: 'grey',
+  info: 'green',
+  debug: 'blue',
+  prompt: 'grey',
+  verbose: 'cyan',
+  input: 'grey',
+  silly: 'magenta'
+};