The info parameter provided to a given format represents a single log
message. The object itself is mutable. Every info must have at least the
level and message properties:
const info = { level: 'info', // Level of the logging message message: 'Hey! Log something?' // Descriptive message being logged.}
Properties besides level and message are considered as "meta". i.e.:
const { level, message, ...meta } = info;
Several of the formats in logform itself add additional properties:
Property
Format added by
Description
splat
splat()
String interpolation splat for %d %s-style messages.
timestamp
timestamp()
timestamp the message was received.
label
label()
Custom label associated with each message.
ms
ms()
Number of milliseconds since the previous log message.
As a consumer you may add whatever properties you wish – internal state is
maintained by Symbol properties:
Symbol.for('level')(READ-ONLY): equal to level property.
Is treated as immutable by all code.
Symbol.for('message'): complete string message set by "finalizing formats":
json
logstash
printf
prettyPrint
simple
Symbol.for('splat'): additional string interpolation arguments. Used
exclusively by splat() format.
These Symbols are stored in another package: triple-beam so that all
consumers of logform can have the same Symbol reference. i.e.:
Formats are prototypal objects (i.e. class instances) that define a single method: transform(info, opts) and return the mutated info
info: an object representing the log message.
opts: setting specific to the current instance of the format.
They are expected to return one of two things:
An info Object representing the modified info argument. Object references need not be preserved if immutability is preferred. All current built-in formats consider info mutable, but [immutablejs] is being considered for future releases.
A falsey value indicating that the info argument should be ignored by the caller. (See: Filtering info Objects) below.
logform.format is designed to be as simple as possible. To define a new format simple pass it a transform(info, opts) function to get a new Format.
The named Format returned can be used to create as many copies of the given Format as desired:
const { format } = require('logform');const volume = format((info, opts) => { if (opts.yell) { info.message = info.message.toUpperCase(); } else if (opts.whisper) { info.message = info.message.toLowerCase(); } return info;});// `volume` is now a function that returns instances of the format.const scream = volume({ yell: true });console.dir(scream.transform({ level: 'info', message: `sorry for making you YELL in your head!`}, scream.options));// {// level: 'info'// message: 'SORRY FOR MAKING YOU YELL IN YOUR HEAD!'// }// `volume` can be used multiple times to create different formats.const whisper = volume({ whisper: true });console.dir(whisper.transform({ level: 'info', message: `WHY ARE THEY MAKING US YELL SO MUCH!`}), whisper.options);// {// level: 'info'// message: 'why are they making us yell so much!'// }
Combining formats
Any number of formats may be combined into a single format using format.combine. Since format.combine takes no opts, as a convenience it returns pre-created instance of the combined format.
const { format } = require('logform');const { combine, timestamp, label } = format;const labelTimestamp = combine( label({ label: 'right meow!' }), timestamp());const info = labelTimestamp.transform({ level: 'info', message: 'What time is the testing at?'});console.dir(info);// { level: 'info',// message: 'What time is the testing at?',// label: 'right meow!',// timestamp: '2017-09-30T03:57:26.875Z' }
Filtering info Objects
If you wish to filter out a given info Object completely then simply return a falsey value.
const ignorePrivate = format((info, opts) => { if (info.private) { return false; } return info;});console.dir(ignorePrivate.transform({ level: 'error', message: 'Public error to share'}));// { level: 'error', message: 'Public error to share' }console.dir(ignorePrivate.transform({ level: 'error', private: true, message: 'This is super secret - hide it.'}));// false
Use of format.combine will respect any falsey values return and stop evaluation of later formats in the series. For example:
This was previously exposed as { align: true } in winston < 3.0.0.
CLI
The cli format is a combination of the colorize and the padLevels formats. It turns a log info object into the same format previously available in winston.cli() in winston < 3.0.0.
The errors format allows you to pass in an instance of a JavaScript Error
directly to the logger. It allows you to specify whether not to include the
stack-trace.
const { format } = require('logform');const { errors } = format;const errorsFormat = errors({ stack: true })const info = errorsFormat.transform(new Error('Oh no!'));console.log(info);// Error: Oh no!// at repl:1:13// at ContextifyScript.Script.runInThisContext (vm.js:50:33)// at REPLServer.defaultEval (repl.js:240:29)// at bound (domain.js:301:14)// at REPLServer.runBound [as eval] (domain.js:314:12)// at REPLServer.onLine (repl.js:468:10)// at emitOne (events.js:121:20)// at REPLServer.emit (events.js:211:7)// at REPLServer.Interface._onLine (readline.js:282:10)// at REPLServer.Interface._line (readline.js:631:8)
It will also handle { message } properties as Error instances:
const { format } = require('logform');const { errors } = format;const errorsFormat = errors({ stack: true })const info = errorsFormat.transform({ message: new Error('Oh no!')});console.log(info);// Error: Oh no!// at repl:1:13// at ContextifyScript.Script.runInThisContext (vm.js:50:33)// at REPLServer.defaultEval (repl.js:240:29)// at bound (domain.js:301:14)// at REPLServer.runBound [as eval] (domain.js:314:12)// at REPLServer.onLine (repl.js:468:10)// at emitOne (events.js:121:20)// at REPLServer.emit (events.js:211:7)// at REPLServer.Interface._onLine (readline.js:282:10)// at REPLServer.Interface._line (readline.js:631:8)
JSON
The json format uses safe-stable-stringify to finalize the message.
It accepts the following options:
replacer: A function that influences how the info is stringified.
space: The number of white space used to format the json.
This was previously exposed as { logstash: true } to transports in winston < 3.0.0.
Metadata
The metadata format adds a metadata object to collect extraneous data, similar to the metadata object in winston 2.x.
It accepts the following options:
key: The name of the key used for the metadata object. Defaults to metadata.
fillExcept: An array of keys that should not be added to the metadata object.
fillWith: An array of keys that will be added to the metadata object.
Any additional splat parameters beyond those needed for the % tokens
(aka "metas") are assumed to be objects. Their enumerable properties are
merged into the info.
This was previously exposed implicitly in winston < 3.0.0.
Timestamp
The timestamp format adds a timestamp to the info.
It accepts the following options:
format: Either the format as a string accepted by the fecha module or a function that returns a formatted date. If no format is provided new Date().toISOString() will be used.
alias: The name of an alias for the timestamp property, that will be added to the info object.