Document the solution to #1486. (#1554)

* [doc] Document the solution to #1486.

* [doc] Show both in example.

* [doc] Update the examples.

Author: indexzero

README.md

@@ -235,6 +235,21 @@ treated as immutable by all code.
 - `Symbol.for('message'):` complete string message set by "finalizing 
 formats": `json`, `logstash`, `printf`, `prettyPrint`, and `simple`. 
 
+> **NOTE:** the `message` and `level` properties are considered reserved.
+> Please be aware of this when logging additional metadata objects. For 
+> example the below will suppress the `message` property of the metadata
+> provided:
+>
+> ``` js
+> logger.log('hello', { message: 'will be hidden' });
+> ```
+> 
+> To work around this use the `splat()` format below. e.g.:
+> 
+> ``` js
+> logger.log('hello %j', { message: 'will be shown' });
+> ```
+
 ## Formats
 
 Formats in `winston` can be accessed from `winston.format`. They are

examples/splat-message.js

@@ -0,0 +1,28 @@
+const winston = require('../');
+
+const loggers = {
+  splat: winston.createLogger({
+    level: 'info',
+    format: winston.format.combine(
+      winston.format.splat(),
+      winston.format.simple()
+    ),
+    transports: [new winston.transports.Console()],
+  }),
+  simple: winston.createLogger({
+    level: 'info',
+    format: winston.format.simple(),
+    transports: [new winston.transports.Console()],
+  })
+};
+
+const meta = {
+  subject: 'Hello, World!',
+  message: 'This message is a unique property separate from implicit merging.',
+};
+
+loggers.simple.info('email.message is hidden', meta);
+loggers.simple.info('email.message is hidden %j\n', meta);
+
+loggers.splat.info('This is overridden by meta', meta);
+loggers.splat.info('email.message is shown %j', meta);