From 7f75b48c559edbcfdcf73c445bcc395cbd29a782 Mon Sep 17 00:00:00 2001
From: indexzero <charlie.robbins@gmail.com>
Date: Tue, 9 Jun 2015 13:43:33 -0700
Subject: [PATCH] [doc] Add documentation for rewriters.

---
 README.md | 37 +++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 306a5147f..8bba8c3c6 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,7 @@ There are two different ways to use winston: directly via the default logger, or
   * [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](#filters)
+  * [Filters and Rewriters](#filters-and-rewriters)
 * [Working with transports](#working-with-transports)
     * [Adding Custom Transports](#adding-custom-transports)
 * [Installation](#installation)
@@ -631,14 +631,16 @@ Often in a given code base with lots of Loggers it is useful to add logging meth
   myObject.info("127.0.0.1 - there's no place like home");
 ```
 
-### Filters
-Filters allow modifying the contents of log messages, e.g. to mask data that
-should not appear in logs.
+### 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.
 
 ``` js
-logger.addFilter(function(msg) {
-  return maskCardNumbers(msg);
+logger.addFilter(function(msg, meta, level) {
+  return meta.production
+    ? maskCardNumbers(msg)
+    : msg;
 });
+
 logger.info('transaction with card number 123456789012345 successful.');
 ```
 
@@ -648,8 +650,27 @@ This may result in this output:
 info: transaction with card number 123456****2345 successful.
 ```
 
-See [log-filter-test.js](./test/log-filter-test.js), where card number masking
-is implemented as an example.
+Where as for rewriters, if you wanted to sanitize the `creditCard` field of your `meta` you could:
+
+``` js
+logger.addRewriter(function(level, msg, meta) {
+  if (meta.creditCard) {
+    meta.creditCard = maskCardNumbers(meta.creditCard)
+  }
+
+  return meta;
+});
+
+logger.info('transaction ok', { creditCard: 123456789012345 });
+```
+
+which may result in this output:
+
+```
+info: transaction ok creditCard=123456****2345
+```
+
+See [log-filter-test.js](./test/log-filter-test.js), where card number masking is implemented as an example along with [log-rewriter-test.js](./test/log-rewriter-test.js)
 
 ## Working with Transports
 There are many 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__