diff --git a/README.md b/README.md index c23f52888..b5eadf0be 100644 --- a/README.md +++ b/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 diff --git a/examples/splat-message.js b/examples/splat-message.js new file mode 100644 index 000000000..c6b2ca69c --- /dev/null +++ b/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);