Security News
Introducing the Socket Python SDK
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
By Douglas Coburn - Sep 13, 2024
logform
An mutable object-based log format designed for chaining & objectMode streams.
What is logform?
The logform npm package is a module designed for formatting messages in logging systems, primarily used with the popular Winston logger. It provides a way to define how log messages should be formatted before they are written to a console, file, or any other transport.
What are logform's main functionalities?
Simple message formatting
This feature allows users to create custom message formats using the printf function from logform. It enables the inclusion of timestamp, label, level, and message in the log output.
const { format } = require('logform');
const { printf } = format;
const myFormat = printf(({ level, message, label, timestamp }) => {
return `${timestamp} [${label}] ${level}: ${message}`;
});
// Use this format in a Winston loggerColorizing the output
This feature provides an easy way to add color to log messages based on the log level, enhancing readability especially when viewing logs directly from consoles.
const { format } = require('logform');
const { colorize } = format;
const colorizedFormat = colorize();
// This format can be used to add colors to different levels of log messages when used with Winston loggerCombining multiple formats
This feature allows the combination of multiple formatting methods such as adding labels, timestamps, and custom printf templates to create a highly customized log output.
const { format } = require('logform');
const { combine, timestamp, label, printf } = format;
const combinedFormats = combine(
label({ label: 'My App' }),
timestamp(),
printf(info => `${info.timestamp} [${info.label}] ${info.level}: ${info.message}`)
);
// This combined format can be used in a Winston logger to provide a rich structured outputOther packages similar to logform
winston
Winston is a multi-transport async logging library for Node.js. While logform is primarily used as a formatting tool within Winston, Winston itself provides more comprehensive logging solutions including transports management, which logform does not handle.
bunyan
Bunyan is another logging library that focuses on JSON logging. Unlike logform, which is used for formatting log messages, Bunyan handles both the logging and formatting but emphasizes a JSON structure for output, making it ideal for machine parsing.
pino
Pino is a very low overhead Node.js logger, similar to Bunyan but focuses on performance. It includes its own set of formatting capabilities but is generally used for its performance benefits over extensive formatting options.
logform
A mutable object-based log format designed for chaining & objectMode streams.
const { format } = require('logform');
const alignedWithColorsAndTime = format.combine(
format.colorize(),
format.timestamp(),
format.align(),
format.printf(info => `${info.timestamp} ${info.level}: ${info.message}`)
);
info Objects
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 tolevelproperty. Is treated as immutable by all code.Symbol.for('message'):complete string message set by "finalizing formats":jsonlogstashprintfprettyPrintsimple
Symbol.for('splat'): additional string interpolation arguments. Used exclusively bysplat()format.
These Symbols are stored in another package: triple-beam so that all
consumers of logform can have the same Symbol reference. i.e.:
const { LEVEL, MESSAGE, SPLAT } = require('triple-beam');
console.log(LEVEL === Symbol.for('level'));
// true
console.log(MESSAGE === Symbol.for('message'));
// true
console.log(SPLAT === Symbol.for('splat'));
// true
Understanding formats
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
infoObject representing the modifiedinfoargument. Object references need not be preserved if immutability is preferred. All current built-in formats considerinfomutable, but [immutablejs] is being considered for future releases. - A falsey value indicating that the
infoargument should be ignored by the caller. (See: FilteringinfoObjects) 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:
const { format } = require('logform');
const { combine, timestamp, label } = format;
const willNeverThrow = format.combine(
format(info => { return false })(), // Ignores everything
format(info => { throw new Error('Never reached') })()
);
console.dir(willNeverThrow.transform({
level: 'info',
message: 'wow such testing'
}))
Formats
Align
The align format adds a \t delimiter before the message to align it in the same place.
const { format } = require('logform');
const alignFormat = format.align();
const info = alignFormat.transform({
level: 'info',
message: 'my message'
});
console.log(info);
// { level: 'info', message: '\tmy message' }
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.
const { format } = require('logform');
const LEVEL = Symbol.for('level');
const cliFormat = format.cli({ colors: { info: 'blue' }});
const info = cliFormat.transform({
[LEVEL]: 'info',
level: 'info',
message: 'my message'
}, { all: true });
console.log(info);
// { level: '\u001b[34minfo\u001b[39m',
// message: '\u001b[34m my message\u001b[39m',
// [Symbol(level)]: 'info',
// [Symbol(message)]:
// '\u001b[34minfo\u001b[39m:\u001b[34m my message\u001b[39m' }
Colorize
The colorize format adds different colors depending on the log level to the message and/or level.
It accepts the following options:
- level: If set to
truethe color will be applied to thelevel. - all: If set to
truethe color will be applied to themessageandlevel. - message: If set to
truethe color will be applied to themessage. - colors: An object containing the colors for the log levels. For example:
{ info: 'blue', error: 'red' }
const { format } = require('logform');
const LEVEL = Symbol.for('level');
const colorizeFormat = format.colorize({ colors: { info: 'blue' }});
const info = colorizeFormat.transform({
[LEVEL]: 'info',
level: 'info',
message: 'my message'
}, { all: true });
console.log(info);
// { level: '\u001b[34minfo\u001b[39m',
// message: '\u001b[34mmy message\u001b[39m',
// [Symbol(level)]: 'info' }
This was previously exposed as { colorize: true } to transports in winston < 3.0.0.
Combine
The combine Format allows to combine multiple formats:
const { format } = require('logform');
const { combine, timestamp, json } = format;
const jsonWithTimestamp = combine(
timestamp(),
json()
);
const info = jsonWithTimestamp.transform({
level: 'info',
message: 'my message'
});
console.log(info);
// { level: 'info',
// message: 'my message',
// timestamp: '2018-10-02T15:03:14.230Z',
// [Symbol(message)]:
// '{"level":"info","message":"my message","timestamp":"2018-10-02T15:03:14.230Z"}' }
Errors
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
infois stringified. - space: The number of white space used to format the json.
const { format } = require('logform');
const jsonFormat = format.json();
const info = jsonFormat.transform({
level: 'info',
message: 'my message',
});
console.log(info);
// { level: 'info',
// message: 'my message',
// [Symbol(message)]: '{"level":"info","message":"my message"}' }
This was previously exposed as { json: true } to transports in winston < 3.0.0.
Label
The label format adds the specified label before the message or adds it to the info object.
It accepts the following options:
- label: A label to be added before the message.
- message: If set to
truethelabelwill be added toinfo.message. If set tofalsethelabelwill be added asinfo.label.
const { format } = require('logform');
const labelFormat = format.label();
const info = labelFormat.transform({
level: 'info',
message: 'my message'
}, { label: 'my label', message: true });
console.log(info);
// { level: 'info', message: '[my label] my message' }
This was previously exposed as { label: 'my label' } to transports in winston < 3.0.0.
Logstash
The logstash Format turns a log info object into pure JSON with the appropriate logstash options.
const { format } = require('logform');
const { logstash, combine, timestamp } = format;
const logstashFormat = combine(
timestamp(),
logstash()
);
const info = logstashFormat.transform({
level: 'info',
message: 'my message'
});
console.log(info);
// { level: 'info',
// [Symbol(message)]:
// '{"@message":"my message","@timestamp":"2018-10-02T11:04:52.915Z","@fields":{"level":"info"}}' }
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.
const { format } = require('logform');
const metadataFormat = format.metadata();
const info = metadataFormat.transform({
level: 'info',
message: 'my message',
meta: 42
});
console.log(info);
// { level: 'info', message: 'my message', metadata: { meta: 42 } }
PadLevels
The padLevels format pads levels to be the same length.
const { format } = require('logform');
const LEVEL = Symbol.for('level');
const padLevelsFormat = format.padLevels();
const info = padLevelsFormat.transform({
[LEVEL]: 'info',
message: 'my message'
});
console.log(info);
// { message: ' my message', [Symbol(level)]: 'info' }
This was previously exposed as { padLevels: true } to transports in winston < 3.0.0.
PrettyPrint
The prettyPrint format finalizes the message using util.inspect.
It accepts the following options:
- depth: A
numberthat specifies the maximum depth of theinfoobject being stringified byutil.inspect. Defaults to2. - colorize: Colorizes the message if set to
true. Defaults tofalse.
The prettyPrint format should not be used in production because it may impact performance negatively and block the event loop.
NOTE: the
LEVEL,MESSAGE, andSPLATsymbols are stripped from the output message by design.
This was previously exposed as { prettyPrint: true } to transports in winston < 3.0.0.
const { format } = require('logform');
const prettyPrintFormat = format.prettyPrint();
const info = prettyPrintFormat.transform({
[LEVEL]: 'info',
level: 'info',
message: 'my message'
});
console.log(info);
// { level: 'info',
// message: 'my message',
// [Symbol(level)]: 'info',
// [Symbol(message)]: '{ level: \'info\', message: \'my message\' }' }
Printf
The printf format allows to create a custom logging format:
const { format } = require('logform');
const myFormat = format.printf((info) => {
return `${info.level} ${info.message}`;
})
const info = myFormat.transform({
level: 'info',
message: 'my message'
});
console.log(info);
// { level: 'info',
// message: 'my message',
// [Symbol(message)]: 'info my message' }
Simple
The simple format finalizes the info object using the format: level: message stringifiedRest.
const { format } = require('logform');
const MESSAGE = Symbol.for('message');
const simpleFormat = format.simple();
const info = simpleFormat.transform({
level: 'info',
message: 'my message',
number: 123
});
console.log(info[MESSAGE]);
// info: my message {number:123}
Splat
The splat format transforms the message by using util.format to complete any info.message provided it has string interpolation tokens.
const { format } = require('logform');
const splatFormat = format.splat();
const info = splatFormat.transform({
level: 'info',
message: 'my message %s',
splat: ['test']
});
console.log(info);
// { level: 'info', message: 'my message test', splat: [ 'test' ] }
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.
const { format } = require('logform');
const splatFormat = format.splat();
const info = splatFormat.transform({
level: 'info',
message: 'my message %s',
splat: ['test', { thisIsMeta: true }]
});
console.log(info);
// { level: 'info',
// message: 'my message test',
// thisIsMeta: true,
// splat: [ 'test' ] }
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
infoobject.
const { format } = require('logform');
const timestampFormat = format.timestamp();
const info = timestampFormat.transform({
level: 'info',
message: 'my message'
});
console.log(info);
// { level: 'info',
// message: 'my message',
// timestamp: '2018-10-02T11:47:02.682Z' }
It was previously available in winston < 3.0.0 as { timestamp: true } and { timestamp: function:String }.
Uncolorize
The uncolorize format strips colors from info objects.
It accepts the following options:
- level: Disables the uncolorize format for
info.levelif set tofalse. - message: Disables the uncolorize format for
info.messageif set tofalse. - raw: Disables the uncolorize format for
info[MESSAGE]if set tofalse.
This was previously exposed as { stripColors: true } to transports in winston < 3.0.0.
Tests
Tests are written with mocha, assume, and nyc. They can be run with npm:
npm test
LICENSE: MIT
AUTHOR: Charlie Robbins
FAQs
An mutable object-based log format designed for chaining & objectMode streams.
We found that logform demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Package last updated on 10 Jul 2024
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Security News
The Wildcard Gamble: Understanding the Risks of Floating Dependency Ranges in npm
Floating dependency ranges in npm can introduce instability and security risks into your project by allowing unverified or incompatible versions to be installed automatically, leading to unpredictable behavior and potential conflicts.
By Sarah Gooding - Sep 13, 2024
Security News
New Rust RFC Proposes Adding Support for Trusted Publishing to Crates.io
A new Rust RFC proposes "Trusted Publishing" for Crates.io, introducing short-lived access tokens via OIDC to improve security and reduce risks associated with long-lived API tokens.
By Sarah Gooding - Sep 12, 2024